@jini-ai/cms 0.5.2 → 0.5.4

package/dist/seo/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * @file SEO core type definitions (SPEC-008, ADR-PIPE-008).
+ *
+ * Types ONLY — no feature logic. Fills in the ADR-032 design-only stub with
+ * the shapes ADR-PIPE-008 actually commits to. Deviations from the original
+ * stub (state.spec.md §5 + ADR-PIPE-008 Context, all disclosed there):
+ *  - No `baseUrl`/`seo.base_url` anywhere (INV-07 — single-origin-authority;
+ *    every absolute URL comes from `routing.urlFor`'s `canonicalUrl`).
+ *  - `RobotsPolicy` stays computed-only (`sitemapUrls` is never persisted);
+ *    only `robotsRules: RobotsRule[]` is stored.
+ *  - `SeoPermission`'s 5-string vocabulary is replaced by the single string
+ *    `"admin.seo.manage"`, used directly at call sites (no type needed).
+ *  - `SeoFieldDecl`/`SeoExpressionIndexDecl` (ADR-022 generic-entries-model
+ *    registration vocabulary) are dropped — this feature stores overrides on
+ *    the bespoke `posts.seo_ext_json` column (state.spec.md §0), not a
+ *    generic ext-bag with a content-type field registry.
+ *  - `HeadElement`/`HeadElementKey`/`PageHeadContext`/`PageHeadEntryRef` live
+ *    canonically in `src/server/http/site/page-head.ts` (ADR-PIPE-008
+ *    Decision §2 — the render seam is core-owned, not SEO-owned); as of
+ *    2026-08-20 (RouteDeps-narrowing pass 3) this file holds a structural
+ *    DUPLICATE of them, not a re-export — see the block comment just above
+ *    their declarations below for why.
+ */
+import type { ISODateTime, JsonObject, UUID } from "@jini-ai/core/primitives";
+/**
+ * Structural duplicate of `server/http/site/page-head.ts`'s `HeadElement`/`HeadElementKey`/
+ * `JsonLd`/`PageHeadContext`/`PageHeadEntryRef`/`PageHeadHook` — NOT a re-export, as of the
+ * 2026-08-20 RouteDeps-narrowing pass 3 (`check:architecture`'s `backEdgesIntoServer` metric counts
+ * a type-only `export type {...} from ".../server/..."` re-export as a real graph edge, same as any
+ * other import — the `--ts-pre-compilation-deps` resolution `route-manifest.ts`'s own header already
+ * documents for this exact shape of edge).
+ *
+ * OWNERSHIP IS UNCHANGED: `page-head.ts` still owns these types canonically. That is a settled,
+ * deliberate decision — ADR-PIPE-008 Decision §2 explicitly considered and REJECTED keeping this
+ * seam inside `src/seo/` ("Wrong ownership — a future non-SEO contributor [the feeds plugin, ADR-032
+ * §4] would have to import the SEO module... couples the render layer to a feature module. Not
+ * selected — ADR-032 itself frames this as the theme layer's seam, not SEO's."). Do not "fix" this
+ * duplicate by turning it back into an import, and do not move these types into this file's own
+ * canonical ownership — both would reopen that rejected alternative.
+ *
+ * `seo/page-head-contributor.ts` never calls `registerPageHeadContributor` itself (only
+ * `server/app.ts` does, at boot) — it only builds a `PageHeadHook`-shaped VALUE, so nothing here
+ * needs the nominal identity of the real types, only their structure.
+ *
+ * Drift safety net — verified empirically with two DIFFERENT perturbations, not asserted from one
+ * (a claim this shape has been wrong before in this codebase). Both were applied to this file, typo
+ * checked with `npx tsc -p tsconfig.json --noEmit`, and reverted:
+ *
+ * 1. Dropped `canonicalUrl` from this file's `PageHeadContext` (a field `page-head-contributor.ts`'s
+ *    `handle` body actually reads). Failed immediately, INSIDE `seo/`, before ever reaching the
+ *    wiring call: `page-head-contributor.ts(34,55): error TS2339: Property 'canonicalUrl' does not
+ *    exist on type 'PageHeadContext'.` — an even earlier tripwire than the wiring call, for any
+ *    drift that touches a field this file's own contributor actually uses.
+ * 2. Changed `PageHeadEntryRef.ext`'s type here from `Record<string, unknown>` to `string` — a field
+ *    NOTHING in `page-head-contributor.ts` reads, chosen specifically to test whether the wiring call
+ *    is a genuinely independent backstop rather than redundant with case 1. It fired exactly there:
+ *    `server/app.ts(796,5): error TS2345: Argument of type '...PageHeadHook' [seo/types.ts] is not
+ *    assignable to parameter of type '...PageHeadHook' [server/http/site/page-head.ts]... Types of
+ *    property 'ext' are incompatible. Type 'Record<string, unknown>' is not assignable to type
+ *    'string'.` — at `registerPageHeadContributor(createSeoPageHeadHook(...))`, line 796.
+ *
+ * So the real guarantee is TWO-LAYERED: a drift in a field this contributor reads fails fast, inside
+ * `seo/`, at the point of use; a drift in a field it does NOT read still fails, loudly, at the
+ * `server/app.ts` wiring call — there is no incompatible-drift shape that both layers miss silently.
+ */
+/** JSON-LD is a plain JSON object graph (schema.org) — duplicate of `page-head.ts`'s `JsonLd`. */
+export type JsonLd = JsonObject;
+interface HeadElementBase {
+    /** behavior.spec.md §2.1's fixed priority bands and dedup comparator — see `page-head.ts`'s own
+     *  `HeadElementBase` doc for the full rule; unchanged here. */
+    readonly priority: number;
+}
+/** Duplicate of `page-head.ts`'s `HeadElement` — see this file's own header for why. */
+export type HeadElement = (HeadElementBase & {
+    readonly kind: "title";
+    readonly text: string;
+}) | (HeadElementBase & {
+    readonly kind: "meta";
+    readonly name: string;
+    readonly content: string;
+}) | (HeadElementBase & {
+    readonly kind: "og";
+    readonly property: string;
+    readonly content: string;
+}) | (HeadElementBase & {
+    readonly kind: "link";
+    readonly rel: string;
+    readonly href: string;
+    readonly hreflang?: string | undefined;
+    /** MIME type, e.g. `application/rss+xml` on a feed's `rel="alternate"`. Part of the dedup key. */
+    readonly type?: string | undefined;
+    readonly title?: string | undefined;
+}) | (HeadElementBase & {
+    readonly kind: "jsonld";
+    readonly data: JsonLd;
+});
+/** Stable dedup key for a HeadElement — duplicate of `page-head.ts`'s `HeadElementKey`. */
+export type HeadElementKey = string;
+/** Duplicate of `page-head.ts`'s `PageHeadEntryRef` — see this file's own header for why. */
+export interface PageHeadEntryRef {
+    id: UUID;
+    type: string;
+    slug: string;
+    title: string;
+    status: string;
+    publishedAt?: ISODateTime | undefined;
+    updatedAt: ISODateTime;
+    ext: Record<string, unknown>;
+    excerpt?: string | undefined;
+    ancestors?: ReadonlyArray<{
+        title: string | undefined;
+        url: string;
+    }>;
+}
+/** Duplicate of `page-head.ts`'s `PageHeadContext` — see this file's own header for why. */
+export interface PageHeadContext {
+    workspaceId: UUID;
+    route: string;
+    contentType?: string | undefined;
+    entry?: PageHeadEntryRef | undefined;
+    canonicalUrl: string;
+    siteTitle: string;
+    locale?: string | undefined;
+    themeTier?: string | undefined;
+}
+/** Duplicate of `page-head.ts`'s `PageHeadHook` — see this file's own header for why. */
+export interface PageHeadHook {
+    readonly priority: number;
+    handle(ctx: PageHeadContext): Promise<HeadElement[]>;
+}
+/** Twitter card kind (Twitter/X card meta). */
+export type TwitterCardKind = "summary" | "summary_large_image";
+/** OpenGraph object type (v1 subset). */
+export type OpenGraphType = "website" | "article" | "profile";
+/**
+ * The author-authored override bag persisted at `posts.seo_ext_json`. Every
+ * field is OPTIONAL — absence means "derive from the entry + site defaults".
+ * Unregistered keys are rejected at the write chokepoint (`write-service.ts`);
+ * this interface is the registered, validated shape.
+ *
+ * `ogImage`/`twitterImage` hold a media *ref* (`"{assetId}:{transformName}"`)
+ * or an absolute URL — never a frozen `/m/` URL directly (ADR-027 §4: internal
+ * content stores refs, not URLs) — resolved to a URL at read time by `media.ts`.
+ */
+export interface SeoExtFields {
+    /** Meta title override; falls back to `entry.title` run through the template. */
+    title?: string | undefined;
+    /** Meta description override; falls back to site default / excerpt. */
+    description?: string | undefined;
+    /** Canonical URL override (absolute); falls back to the routing-resolved URL. */
+    canonical?: string | undefined;
+    /** Exclude from indexing (emits `robots: noindex` + drops from the sitemap). */
+    noindex?: boolean | undefined;
+    /** Emit `robots: nofollow`. */
+    nofollow?: boolean | undefined;
+    /** JSON-LD schema.org @type override (else derived from content type). */
+    schemaType?: string | undefined;
+    /** OpenGraph overrides. */
+    ogTitle?: string | undefined;
+    ogDescription?: string | undefined;
+    ogImage?: string | undefined;
+    ogType?: OpenGraphType | undefined;
+    /** Twitter/X card overrides. */
+    twitterCard?: TwitterCardKind | undefined;
+    twitterTitle?: string | undefined;
+    twitterDescription?: string | undefined;
+    twitterImage?: string | undefined;
+}
+/**
+ * The shape `setEntrySeoOverrides` (`write-service.ts`) accepts as its `patch`. Widens every
+ * `SeoExtFields` field to also allow `null`, meaning "remove this key" — the override is cleared
+ * back to absent so resolution (`seo.ts`) falls through to the site default / derived value, the
+ * same "pass null to clear" vocabulary `SeoSettings`' own nullable fields
+ * (`defaultDescription`/`defaultOgImage`/`twitterSite`, see `settings.ts`) already use. `undefined`
+ * (an omitted key) still means "leave unchanged" — only an explicit `null` clears.
+ *
+ * Clearing EVERY currently-set key in one patch (e.g. `{ description: null, title: null, ... }`)
+ * is how the entry's `seoExtJson` is expressible back to its true original `NULL` state, not just
+ * an empty bag — `setEntrySeoOverrides` collapses a merge result with zero remaining keys to `null`
+ * rather than persisting `"{}"` (see that function's own doc comment).
+ */
+export type SeoExtFieldsPatch = {
+    [K in keyof SeoExtFields]?: SeoExtFields[K] | null;
+};
+export interface OpenGraph {
+    title: string;
+    description?: string | undefined;
+    type: OpenGraphType;
+    url: string;
+    image?: string | undefined;
+    siteName?: string | undefined;
+}
+export interface TwitterCard {
+    card: TwitterCardKind;
+    title: string;
+    description?: string | undefined;
+    image?: string | undefined;
+    site?: string | undefined;
+}
+export interface RobotsDirective {
+    noindex: boolean;
+    nofollow: boolean;
+}
+/** JSON-LD is a plain JSON object graph (schema.org). */
+export type JsonLdObject = JsonObject;
+/**
+ * The fully-resolved effective meta for one page: author overrides layered
+ * over site defaults layered over derived-from-entry (behavior.spec.md §1.1).
+ * This is the single source `getEntryMeta`/`analyzeEntry`/the head contributor
+ * all read (one evaluator, no back door — INV-09).
+ */
+export interface SeoMeta {
+    title: string;
+    description?: string | undefined;
+    canonical: string;
+    robots: RobotsDirective;
+    openGraph: OpenGraph;
+    twitter: TwitterCard;
+    jsonLd: JsonLdObject[];
+}
+export type ChangeFreq = "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+export interface SitemapEntry {
+    loc: string;
+    lastmod?: string | undefined;
+    changefreq?: ChangeFreq | undefined;
+    /** 0.0–1.0. */
+    priority?: number | undefined;
+}
+/** Context handed to the (v1 empty) `seo.sitemap.collect` hook. */
+export interface SitemapCollectContext {
+    workspaceId: string;
+    baseUrl: string;
+}
+export interface RobotsRule {
+    userAgent: string;
+    allow?: string[] | undefined;
+    disallow?: string[] | undefined;
+}
+/** Computed at `buildRobots()` read time — never persisted as one shape (state.spec.md §5 item 4). */
+export interface RobotsPolicy {
+    rules: RobotsRule[];
+    /** Absolute sitemap URLs advertised in robots.txt (`[]` when `sitemapEnabled` is false). */
+    sitemapUrls: string[];
+}
+/**
+ * Registered `site.seo.*` ledger keys (ADR-PIPE-008 Decision §3's mapping
+ * table — 8 registered keys backing 7 `SeoSettings` fields, since
+ * `defaultRobots` decomposes into 2 booleans; see `settings.ts`'s file header
+ * for the disclosed "7 vs 8" tasks.md wording note).
+ */
+export type SeoSettingKey = "title_template" | "default_description" | "default_og_image" | "twitter_site" | "default_robots_noindex" | "default_robots_nofollow" | "sitemap_enabled" | "robots_rules";
+/** The resolved, workspace-scoped SEO settings. No `baseUrl` field exists (INV-07). */
+export interface SeoSettings {
+    /** e.g. `"%s — My Site"`; `%s` is the per-page title. */
+    titleTemplate: string;
+    defaultDescription?: string | undefined;
+    defaultOgImage?: string | undefined;
+    twitterSite?: string | undefined;
+    defaultRobots: RobotsDirective;
+    sitemapEnabled: boolean;
+    robotsRules: RobotsRule[];
+}
+export type SeoIssueSeverity = "error" | "warning" | "info";
+export interface SeoIssue {
+    code: string;
+    severity: SeoIssueSeverity;
+    message: string;
+    /** Which resolved field the issue is about (e.g. `title`, `description`). */
+    field?: keyof SeoMeta & string | undefined;
+}
+export interface SeoAnalysis {
+    entryId: string;
+    score: number;
+    issues: SeoIssue[];
+    resolved: SeoMeta;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/seo/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/seo/write-service.d.ts

@@ -0,0 +1,79 @@
+import { type Clock as ClockPort } from "@jini-ai/core/primitives";
+import { type AuthorizeFn } from "../core/index.js";
+import type { SeoPostWritePort as PostRepoPort, SeoFeaturedImagePort } from "./ports.js";
+type FeaturedImageDeps = {
+    featuredImage: SeoFeaturedImagePort;
+};
+import type { SeoExtFields, SeoExtFieldsPatch } from "./types.js";
+/**
+ * @file `setEntrySeoOverrides` — THE per-entry SEO write chokepoint
+ * (ADR-PIPE-008 Decision §4, C-004; REQ-01/02/03). `authorize("admin.seo.manage")`
+ * -> validate (registered-key-only, length/URL-scheme) -> merge into the
+ * existing (or empty) `posts.seo_ext_json` -> `postRepo.save` -> conditional
+ * direct sitemap-cache invalidation on a noindex/canonical-affecting write.
+ *
+ * No new port: reuses the existing `PostRepoPort` (`findById`/`save`).
+ * `invalidateSitemapCache` is injected (not imported from `sitemap.ts`
+ * directly) so this file stays independently testable in Phase 2, ahead of
+ * Phase 6's `sitemap.ts` existing — the real composition root (Phase 7, T047)
+ * wires the real function in.
+ *
+ * Clearing an override (2026-09-06 fix): a patch value of `null` REMOVES that key from the merged
+ * bag (see `SeoExtFieldsPatch`'s doc comment in `types.ts` for the "pass null to clear" convention
+ * this mirrors from `SeoSettings`). Before this, there was no way to un-set a key once written — the
+ * only options were overwriting it with another value or `""`, and `seo.ts`'s `?? ` precedence chain
+ * does not filter `""`, so an empty-string override silently suppressed the site default/derived
+ * fallback rather than falling through to it. A merge result left with zero keys is persisted as
+ * `seoExtJson: null` (not `"{}"`), so clearing every currently-set key returns the row to its true
+ * original state, not a leftover empty bag.
+ */
+export declare const STRING_FIELD_MAX_LENGTH = 500;
+export declare const URL_FIELD_MAX_LENGTH = 2048;
+/** Fields whose value is a plain string, length-bounded at 500 chars (behavior.spec.md §4). */
+export declare const STRING_FIELDS: ReadonlyArray<keyof SeoExtFields>;
+/** Fields whose value is a URL/media-ref, length-bounded at 2048 chars (behavior.spec.md §4). */
+export declare const URL_FIELDS: ReadonlyArray<keyof SeoExtFields>;
+export declare const BOOLEAN_FIELDS: ReadonlyArray<keyof SeoExtFields>;
+export declare const OG_TYPE_VALUES: readonly ["website", "article", "profile"];
+export declare const TWITTER_CARD_VALUES: readonly ["summary", "summary_large_image"];
+/** Every registered `SeoExtFields` key — an unregistered patch key is rejected outright (INV-01). */
+export declare const REGISTERED_KEYS: ReadonlyArray<string>;
+export interface SetEntrySeoOverridesDeps {
+    postRepo: PostRepoPort;
+    authorize: AuthorizeFn;
+    /** Injected so this chokepoint stays testable ahead of Phase 6's `sitemap.ts` (see file header). */
+    invalidateSitemapCache: (input: {
+        workspaceId: string;
+    }) => void | Promise<void>;
+    /**
+     * `post_revisions` timestamping (2026-09-18, round 4) — see {@link mergeOverridesOntoCurrentRow}'s
+     * updated doc. Required, not optional-with-a-fallback like `createPost`/`updatePost`'s own
+     * `beforeSaveHook`: every real caller (`seo/tool-registrations.ts`, `routes/seo/put-entry.ts`)
+     * already has a `ClockPort` on its own deps bag, so there is no "existing caller with no reachable
+     * clock" case to preserve compiling here the way `CreatePostDeps.beforeSaveHook`'s doc describes.
+     */
+    clock: ClockPort;
+    /** Media lookups for the share-image check (2026-10-05): an `ogImage`/`twitterImage` ref naming a
+     *  video is refused. Required so no write path can skip it by not wiring it. */
+    media: FeaturedImageDeps;
+}
+export interface SetEntrySeoOverridesInput {
+    workspaceId: string;
+    entryId: string;
+    patch: SeoExtFieldsPatch;
+    callerPrincipalId: string;
+}
+export interface SetEntrySeoOverridesRequired {
+    deps: SetEntrySeoOverridesDeps;
+    input: SetEntrySeoOverridesInput;
+}
+/**
+ * REQ-01/02/03 chokepoint write: authorize -> validate -> merge -> save -> conditional cache invalidation.
+ * @throws EntityNotLiveError (via {@link mergeOverridesOntoCurrentRow}, S6 web-high fix plan
+ * 2026-09-24) when the entry is in the Trash — no merge, no version bump, no revision.
+ */
+export declare function setEntrySeoOverrides(required: SetEntrySeoOverridesRequired, _optional?: Record<string, never>): Promise<{
+    overrides: SeoExtFields;
+}>;
+export {};
+//# sourceMappingURL=write-service.d.ts.map

package/dist/seo/write-service.js

@@ -0,0 +1,273 @@
+import { nowIso as clockNowIso } from "@jini-ai/core/primitives";
+import {} from "@jini-ai/core/primitives";
+import { assertEntityLive, ForbiddenError } from "../core/index.js";
+import { SeoConcurrentWriteError, SeoEntryNotFoundError, SeoFieldValidationError, SeoInvalidCanonicalUrlError, } from "./errors.js";
+import { seoImageRefRefusal } from "./media.js";
+/**
+ * @file `setEntrySeoOverrides` — THE per-entry SEO write chokepoint
+ * (ADR-PIPE-008 Decision §4, C-004; REQ-01/02/03). `authorize("admin.seo.manage")`
+ * -> validate (registered-key-only, length/URL-scheme) -> merge into the
+ * existing (or empty) `posts.seo_ext_json` -> `postRepo.save` -> conditional
+ * direct sitemap-cache invalidation on a noindex/canonical-affecting write.
+ *
+ * No new port: reuses the existing `PostRepoPort` (`findById`/`save`).
+ * `invalidateSitemapCache` is injected (not imported from `sitemap.ts`
+ * directly) so this file stays independently testable in Phase 2, ahead of
+ * Phase 6's `sitemap.ts` existing — the real composition root (Phase 7, T047)
+ * wires the real function in.
+ *
+ * Clearing an override (2026-09-06 fix): a patch value of `null` REMOVES that key from the merged
+ * bag (see `SeoExtFieldsPatch`'s doc comment in `types.ts` for the "pass null to clear" convention
+ * this mirrors from `SeoSettings`). Before this, there was no way to un-set a key once written — the
+ * only options were overwriting it with another value or `""`, and `seo.ts`'s `?? ` precedence chain
+ * does not filter `""`, so an empty-string override silently suppressed the site default/derived
+ * fallback rather than falling through to it. A merge result left with zero keys is persisted as
+ * `seoExtJson: null` (not `"{}"`), so clearing every currently-set key returns the row to its true
+ * original state, not a leftover empty bag.
+ */
+// Exported (unchanged values) so `agent-tools.ts`'s published JSON Schema can reuse the exact
+// same bounds/vocabulary this chokepoint validates against, rather than restating them — the same
+// discipline `newsletter/agent-tools.ts` uses for `campaign-write-service.ts`'s `SUBJECT_MAX`/etc.
+export const STRING_FIELD_MAX_LENGTH = 500;
+export const URL_FIELD_MAX_LENGTH = 2048;
+/** Fields whose value is a plain string, length-bounded at 500 chars (behavior.spec.md §4). */
+export const STRING_FIELDS = [
+    "title",
+    "description",
+    "schemaType",
+    "ogTitle",
+    "ogDescription",
+    "twitterTitle",
+    "twitterDescription",
+];
+/** Fields whose value is a URL/media-ref, length-bounded at 2048 chars (behavior.spec.md §4). */
+export const URL_FIELDS = ["canonical", "ogImage", "twitterImage"];
+export const BOOLEAN_FIELDS = ["noindex", "nofollow"];
+export const OG_TYPE_VALUES = ["website", "article", "profile"];
+export const TWITTER_CARD_VALUES = ["summary", "summary_large_image"];
+/** Every registered `SeoExtFields` key — an unregistered patch key is rejected outright (INV-01). */
+export const REGISTERED_KEYS = [
+    ...STRING_FIELDS,
+    ...URL_FIELDS,
+    ...BOOLEAN_FIELDS,
+    "ogType",
+    "twitterCard",
+];
+/** `javascript:`/`data:` (and other script-capable schemes) are never a safe canonical override. */
+const UNSAFE_URL_SCHEME_PATTERN = /^\s*(javascript|data|vbscript|file):/i;
+/**
+ * Pure validation over a raw patch object. Never mutates; throws the first
+ * violation found. Kept separate from the chokepoint so Code Review/tests can
+ * exercise it directly if needed, though `setEntrySeoOverrides` is the only
+ * caller.
+ */
+/** Every patch key must be a known `SeoExtFields` key (INV-01) — checked before any per-field rule. */
+function validateRegisteredKeys(patch) {
+    for (const key of Object.keys(patch)) {
+        if (!REGISTERED_KEYS.includes(key)) {
+            throw new SeoFieldValidationError(`'${key}' is not a registered SEO field`);
+        }
+    }
+}
+/** Shared shape for both STRING_FIELDS and URL_FIELDS: optional string, bounded by `maxLength`.
+ *  `null` is the clear sentinel (see file header) — skipped here, same as `undefined`, since it
+ *  never becomes a stored value for this key. */
+function validateStringLikeFields(patch, fields, maxLength) {
+    for (const key of fields) {
+        const value = patch[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value !== "string") {
+            throw new SeoFieldValidationError(`'${key}' must be a string`);
+        }
+        if (value.length > maxLength) {
+            throw new SeoFieldValidationError(`'${key}' must be at most ${maxLength} characters`);
+        }
+    }
+}
+// Canonical's unsafe-scheme check is its own typed error (SEO_INVALID_CANONICAL_URL),
+// distinct from the generic length/type SEO_FIELD_VALIDATION_ERROR the other field checks throw.
+function validateCanonicalScheme(patch) {
+    const canonical = patch.canonical;
+    if (typeof canonical === "string" && UNSAFE_URL_SCHEME_PATTERN.test(canonical)) {
+        throw new SeoInvalidCanonicalUrlError(`'canonical' uses an unsafe URL scheme`);
+    }
+}
+/** `null` is the clear sentinel (see file header) — skipped, same as `undefined`. */
+function validateBooleanFields(patch) {
+    for (const key of BOOLEAN_FIELDS) {
+        const value = patch[key];
+        if (value !== undefined && value !== null && typeof value !== "boolean") {
+            throw new SeoFieldValidationError(`'${key}' must be a boolean`);
+        }
+    }
+}
+/** `null` is the clear sentinel (see file header) — skipped, same as `undefined`. */
+function validateEnumFields(patch) {
+    if (patch.ogType !== undefined &&
+        patch.ogType !== null &&
+        !OG_TYPE_VALUES.includes(patch.ogType)) {
+        throw new SeoFieldValidationError(`'ogType' must be one of ${OG_TYPE_VALUES.join(", ")}`);
+    }
+    if (patch.twitterCard !== undefined &&
+        patch.twitterCard !== null &&
+        !TWITTER_CARD_VALUES.includes(patch.twitterCard)) {
+        throw new SeoFieldValidationError(`'twitterCard' must be one of ${TWITTER_CARD_VALUES.join(", ")}`);
+    }
+}
+/** Share-image fields whose media ref must be an image (2026-10-05, see `seoImageRefRefusal`). */
+const SHARE_IMAGE_FIELDS = ["ogImage", "twitterImage"];
+/** Refuses a share-image field that names a known non-image asset. Runs after `authorize`, so a
+ *  caller without `admin.seo.manage` cannot probe the media library through its message. */
+async function validateShareImageRefs(media, input) {
+    for (const field of SHARE_IMAGE_FIELDS) {
+        const refusal = await seoImageRefRefusal({ deps: media, input: { workspaceId: input.workspaceId, field, ref: input.patch[field] } });
+        if (refusal)
+            throw new SeoFieldValidationError(refusal);
+    }
+}
+function validateSeoExtFieldsPatch(patch) {
+    validateRegisteredKeys(patch);
+    validateStringLikeFields(patch, STRING_FIELDS, STRING_FIELD_MAX_LENGTH);
+    validateStringLikeFields(patch, URL_FIELDS, URL_FIELD_MAX_LENGTH);
+    validateCanonicalScheme(patch);
+    validateBooleanFields(patch);
+    validateEnumFields(patch);
+}
+/** Fields whose change can flip sitemap eligibility (INV-04/INV-05) — a direct, non-outbox cache-invalidation trigger. */
+const SITEMAP_ELIGIBILITY_FIELDS = ["noindex", "canonical"];
+function touchesSitemapEligibility(patch) {
+    return Object.keys(patch).some((key) => SITEMAP_ELIGIBILITY_FIELDS.includes(key));
+}
+/** Applies `patch` onto `currentOverrides`: a `null` value REMOVES that key (clears the override
+ *  back to absent, see file header); any other value sets/replaces it; `undefined` (an omitted
+ *  key) is left untouched. Pure — never mutates `currentOverrides`. */
+function applyOverridesPatch(currentOverrides, patch) {
+    const merged = { ...currentOverrides };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete merged[key];
+        }
+        else if (value !== undefined) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * How many times the read-merge-write below will re-read a row another writer won underneath it.
+ *
+ * Three, not one, because a single retry is indistinguishable from luck, and not "until it lands",
+ * because an unbounded loop against a hot row is a request that never returns. A row rewritten
+ * three times inside the microtask gaps of one SEO write is not contention, it is something wrong.
+ */
+const MAX_MERGE_ATTEMPTS = 3;
+/**
+ * The SEO chokepoint's whole write: read the row, merge the patch onto whatever it currently holds,
+ * and persist it ONLY while it is still the row that was read.
+ *
+ * Why the predicate (2026-09-07, fable bugs audit SEO-01): this writes the WHOLE row — it is a
+ * `PostRecord` spread, not a one-column UPDATE — so an unconditional `save()` here rewrites
+ * `bodyJson`, `title` and `status` with whatever they were when this function read them. A content
+ * save that landed in the gap was silently reverted by an operator editing a meta description, and
+ * the SEO write reported success. `saveIfVersion` refuses that write instead.
+ *
+ * Why a retry rather than a conflict error: unlike `updatePost`, no SEO caller states a version
+ * basis, so there is nobody to hand a 409 to and nothing for them to reconcile — the patch is a
+ * merge, and re-reading simply merges it onto newer content, which is what the caller asked for.
+ * The caller-visible outcome on a contended row is therefore unchanged (success); what changed is
+ * that it no longer takes the other writer's content down with it.
+ *
+ * Note this DOES still bump `version` on an SEO-only change, which makes an open editor's autosave
+ * basis stale (`PostRepoPort.writeAutosave`'s predicate) and can 409 its next explicit Save. That
+ * is pre-existing behaviour and deliberately unchanged here — it is a contract question about what
+ * `posts.version` means, not a concurrency bug.
+ *
+ * Revision ledger (2026-09-18, round 4): this was the one production write path that bumped
+ * `posts.version` without appending a `post_revisions` row — a real, disclosed bypass
+ * (`2026-09-18-impl-post-revisions-3.md` finding #1). Fixed by reusing the SAME
+ * `PostRepoPort.transaction`/`appendRevision` primitive `createPost`/`updatePost`/`deletePost`
+ * already use for exactly this purpose (`post.ts`), rather than calling `updatePost()` itself:
+ * `updatePost` throws `PostVersionConflictError` on a stale basis, which would turn this function's
+ * own retry-on-conflict loop (the whole point of SEO-01, see above) into a single-shot rejection —
+ * a real behavior change to an already-tested concurrency contract. Reusing the lower primitive
+ * keeps `saveIfVersion`'s retry loop byte-for-byte unchanged while still writing exactly one
+ * revision per successful merge, atomically with the row write it describes.
+ *
+ * @throws SeoEntryNotFoundError when the entry does not exist (or is deleted mid-retry).
+ * @throws EntityNotLiveError (`@jini-ai/cms/core`, S6 web-high fix plan 2026-09-24) when the entry
+ * is in the Trash. Checked every attempt, inside the retry loop, so a row trashed between two
+ * attempts is refused on the next read rather than merged onto and resurrected.
+ * @throws SeoConcurrentWriteError when {@link MAX_MERGE_ATTEMPTS} reads all lost the row.
+ * @complexity O(attempts) queries, one read + one conditional write (+ one revision append on the
+ * attempt that lands) each; one of each in the uncontended case.
+ */
+async function mergeOverridesOntoCurrentRow(postRepo, clock, input) {
+    for (let attempt = 0; attempt < MAX_MERGE_ATTEMPTS; attempt += 1) {
+        const existing = await postRepo.findById({ workspaceId: input.workspaceId, id: input.entryId });
+        if (!existing) {
+            throw new SeoEntryNotFoundError(`entry '${input.entryId}' was not found`);
+        }
+        assertEntityLive({ entityType: existing.kind, entityId: input.entryId, state: postRepo.isTrashed({ post: existing }) ? "trashed" : "live" });
+        const currentOverrides = existing.seoExtJson ? JSON.parse(existing.seoExtJson) : {};
+        const mergedOverrides = applyOverridesPatch(currentOverrides, input.patch);
+        const nextVersion = existing.version + 1;
+        const updatedRecord = {
+            ...existing,
+            // Zero remaining keys returns the row to its true original state (`NULL`), not a leftover
+            // `"{}"` — see file header.
+            seoExtJson: Object.keys(mergedOverrides).length === 0 ? null : JSON.stringify(mergedOverrides),
+            version: nextVersion,
+        };
+        // The write and its revision-ledger append are one atomic unit, same discipline as
+        // `createPost`/`updatePost`/`deletePost` (`post.ts`'s own doc on `PostRepoPort.transaction`) —
+        // a revision must never be recorded for a save that didn't apply, and an applied save must
+        // never land unaccompanied by its revision. A `saveIfVersion` miss (lost the race) returns
+        // normally with `applied: false` rather than throwing, so the transaction still commits (a
+        // harmless no-op) and the outer loop retries with a fresh read, exactly as before this change.
+        const applied = await postRepo.transaction({ fn: async () => {
+                const { applied: didApply } = await postRepo.saveIfVersion({ record: updatedRecord, ifVersion: existing.version });
+                if (!didApply)
+                    return false;
+                await postRepo.appendRevision({
+                    postId: updatedRecord.id,
+                    workspaceId: updatedRecord.workspaceId,
+                    seq: nextVersion,
+                    op: "update",
+                    stateJson: updatedRecord,
+                    actorId: input.callerPrincipalId,
+                    recordedAt: clockNowIso({ clock: clock }),
+                });
+                return true;
+            } });
+        if (applied)
+            return mergedOverrides;
+    }
+    throw new SeoConcurrentWriteError(`entry '${input.entryId}' is being written by another save; the SEO overrides were not applied`);
+}
+/**
+ * REQ-01/02/03 chokepoint write: authorize -> validate -> merge -> save -> conditional cache invalidation.
+ * @throws EntityNotLiveError (via {@link mergeOverridesOntoCurrentRow}, S6 web-high fix plan
+ * 2026-09-24) when the entry is in the Trash — no merge, no version bump, no revision.
+ */
+export async function setEntrySeoOverrides(required, _optional = {}) {
+    const { deps, input } = required;
+    const authResult = await deps.authorize({
+        principalId: input.callerPrincipalId,
+        permission: "admin.seo.manage",
+        workspaceId: input.workspaceId,
+        entityType: "seo-entry",
+        entityId: input.entryId,
+    });
+    if (!authResult.allowed) {
+        throw new ForbiddenError({ message: `principal '${input.callerPrincipalId}' is not authorized for 'admin.seo.manage' (${authResult.reason})`, permission: "admin.seo.manage", reason: authResult.reason });
+    }
+    validateSeoExtFieldsPatch(input.patch);
+    await validateShareImageRefs(deps.media, input);
+    const mergedOverrides = await mergeOverridesOntoCurrentRow(deps.postRepo, deps.clock, input);
+    if (touchesSitemapEligibility(input.patch)) {
+        await deps.invalidateSitemapCache({ workspaceId: input.workspaceId });
+    }
+    return { overrides: mergedOverrides };
+}
+//# sourceMappingURL=write-service.js.map

package/dist/seo/xml-escape.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file The one HTML/XML text escaper. A leaf module with NO imports, on purpose: the old copies
+ * lived inside `render.ts`, `form-render.ts` and `static-render.ts` and were duplicated rather than
+ * shared because importing them would have closed a runtime import cycle. A module that imports
+ * nothing can be imported from anywhere.
+ *
+ * `&` is replaced first: it is the escape character for every entity after it, so replacing any
+ * other character first would double-escape the `&` that replacement introduced. The apostrophe
+ * becomes the numeric `'` in HTML, because `'` is undefined in HTML4/XHTML1.
+ */
+/** {@link escapeHtml} with the XML named entity `'` for the apostrophe (sitemap and feed XML).
+ *  @complexity O(text length). */
+export declare function escapeXml(required: {
+    text: string;
+}, _optional?: Record<string, never>): string;
+//# sourceMappingURL=xml-escape.d.ts.map