Patch a published baseline

Publish an approved bounded baseline patch while preserving the editable draft and reconciling idempotent outcomes.

app_topolo_web.sites.published_baseline.patch creates a new active immutable published version from one exact immutable published baseline. It applies only allowlisted snippet and style-class replacements and preserves the site's current editable draft, even when that draft has diverged from the published version. The current d9 production action capture marks it readOnly: false and requiresConfirmation: true; treat it as a publish operation.

Before execution, confirm publish:write (app_topolo_web.publish:write) for the selected workspace, read the current active published version and exact snippet/style objects, then run app_topolo_web.sites.published_baseline.preview with the same proposed change. Proceed only if the previewed baseVersionId, quality report, rendered preview, and replacement values are still the ones intended. Supply an 8–200 character idempotency key. A request must contain at least one patch; each array is limited to 20 entries. Unknown properties are rejected. siteId, organizationId, workspaceId, and expectedVersionId are required by the current declared input schema.

The following request uses fictional site and workspace values. Its preimage hashes belong only to the synthetic fixture used in the worked cases. Read actual stored objects and compute their canonical hashes before preparing a real request.

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "patch-synth-key-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

The published handler hashes each entire existing snippet/style object as compact UTF-8 JSON, recursively sorting object keys and preserving array order. Any missing object or preimage mismatch fails closed. The site must still be published at expectedVersionId when the compare-and-swap commits. A concurrent publish or changed baseline returns a conflict instead of overwriting a newer version. Quality errors return HTTP 422 with the quality report and a runtime-localized error string. publish_blocked is the action-contract descriptor label, not a verified literal wire value; the exact localized value remains UNKNOWN. Resolve the blocking issue before preparing a fresh preview.

For an identical request retried with the same actor, site, and idempotencyKey, the action can recover the committed result (idempotent: true). Reusing that key for a different request is an idempotency_conflict; use a new key only after re-reading the published version and recomputing every affected preimage. After success, verify the returned version with app_topolo_web.sites.versions.list, confirm it is active, then read the site and confirm its draft is unchanged. To undo a completed patch, use app_topolo_web.sites.versions.restore on the prior version.

The detailed current production catalog requires site, version, qualityReport, urls, preview, and idempotent in the success response. The live action readback omitted outputSchema; the listed success body is source-derived from d9c7581 and no site action was executed. The complete paired responses below are SYNTHETIC / UNRUN examples. For HTTP 403, permission_denied is the action-contract descriptor label; the exact denial body remains UNKNOWN. Use a credential with publish:write in the selected workspace. The source-defined 409 error values and their distinct recovery conditions are listed below. Source lookup misses use site_not_found or version_not_found at HTTP 404 in the same organization/workspace.

Current d9 transport boundary: the declared action input still requires siteId; native action/CLI/MCP callers must supply it. The native SDK consumes that declared value into the trusted {siteId} route path, so the raw HTTP JSON body may omit it after path substitution. If a body siteId is supplied, it must match the path. This is a raw route transport detail, not optionality in the declared action schema.

Source: Reviewed against TopoloWeb d9c75819abedaf71f9436a1d200015883a291072 and the current declared schemas on 2026-10-23. The worked examples below are synthetic and unrun; they are not observed site results.

Responses and errors

These carriers are tied to current production-associated source d9c7581 (186133adb5823723307184dcbd77acb1814317a1, verified provider release association). They describe source branches; no patch action or example was executed. The detailed current production catalog requires site, version, qualityReport, urls, preview, and idempotent on a successful patch response.

Branch	Predicate	Status and body
New publish succeeds	Authorization/parsing pass, patch plan is publishable, and operation reservation/commit succeeds.	200 `{ site, version, qualityReport, urls, preview, idempotent: false }`.
Same-request replay	Same organization/workspace/site/key and matching actor plus complete request digest find a committed operation.	200 `{ site, version, qualityReport, urls, preview, idempotent: true }`. A different actor or request under that key returns a conflict.
Permission denied	`can(..., 'publish:write')` returns a denial.	403 `permission_denied` is the action-contract code; exact body is UNKNOWN because the route returns the `can()` response unchanged.
Invalid request	JSON/schema/refinement fails, including empty patch arrays.	400 `{ error: "invalid_published_baseline_patch" }`.
Body/path mismatch	A supplied body `siteId` differs from the trusted path.	400 `{ error: "site_identity_mismatch" }`.
Scope mismatch	Body organization/workspace differs from authenticated scope.	404 `{ error: "site_not_found" }`.
Typed domain error	Plan or operation raises a patch error.	404 `site_not_found` or `version_not_found`; 400 `invalid_patch`; 409 `site_not_published`, `stale_version`, `preimage_changed`, `idempotency_conflict`, `patch_in_progress`, or `concurrent_publish`, each `{ error: "<code>" }`.
Quality refusal	Patch plan has error-severity quality issues (`!canPublish`).	422 `{ error: <localized publishBlocked string>, qualityReport }`. The localized value is UNKNOWN; source default is “Resolve launch-blocking quality issues before publishing.”

Worked examples

Every case is SYNTHETIC / UNRUN. All identifiers, timestamps, content and hosts are fictional. example.invalid is an explicit fictional runtime-host override, not the production host configuration. Never reuse these fixture values against a real site.

SYNTHETIC / UNRUN — new patch commit

First successful commit; idempotent false. The published snapshot contains the replacements while site.draftContent retains the divergent draft.

Request:

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "patch-synth-key-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

HTTP 200 response body:

{
  "site": {
    "id": "site_synth_01",
    "organizationId": "org-synth-01",
    "workspaceId": "workspace-synth-01",
    "slug": "sample-site",
    "name": "Northstar Studio",
    "status": "published",
    "brief": {
      "intent": "business_site",
      "businessName": "Northstar Studio",
      "businessType": "service",
      "audience": "fictional teams",
      "offer": "launch planning",
      "tone": "clear",
      "differentiators": [],
      "goals": []
    },
    "draftContent": {
      "intent": "business_site",
      "siteTitle": "Northstar Studio",
      "siteDescription": "A fictional service studio for teams preparing a thoughtful launch.",
      "contactEmail": "hello@example.invalid",
      "navigation": [],
      "footerNavigation": [],
      "menus": [],
      "styleClasses": [
        {
          "id": "hero-corners",
          "name": "Hero corners",
          "targetKind": "hero",
          "targetScope": "section",
          "style": {
            "borderRadius": 48
          }
        }
      ],
      "theme": {
        "primary": "#111111",
        "secondary": "#333333",
        "surface": "#ffffff",
        "ink": "#111111",
        "muted": "#444444",
        "accent": "#005fcc",
        "accentSoft": "#111111",
        "glow": "#111111",
        "headingFont": "Inter, system-ui, sans-serif",
        "bodyFont": "Inter, system-ui, sans-serif",
        "radius": "16px"
      },
      "document": {
        "version": 1,
        "pages": [
          {
            "id": "page-home",
            "kind": "page",
            "pageId": "page-home",
            "label": "Home",
            "path": [
              "page-home"
            ],
            "source": {
              "kind": "page",
              "id": "page-home"
            },
            "value": {
              "id": "page-home",
              "slug": "/",
              "title": "Northstar Studio",
              "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
            },
            "children": [
              {
                "kind": "slot",
                "slotKind": "page-body",
                "id": "page-home:body",
                "pageId": "page-home",
                "label": "Page body",
                "path": [
                  "page-home",
                  "slot:body"
                ],
                "parentNodeId": "page-home",
                "source": {
                  "kind": "page",
                  "id": "page-home"
                },
                "accepts": [
                  "layout",
                  "block"
                ],
                "children": [
                  {
                    "kind": "block",
                    "id": "hero-home",
                    "pageId": "page-home",
                    "label": "A clear service path",
                    "path": [
                      "page-home",
                      "slot:body",
                      "sections:0"
                    ],
                    "source": {
                      "kind": "section",
                      "id": "hero-home"
                    },
                    "blockKind": "hero",
                    "sectionKind": "hero",
                    "sectionId": "hero-home",
                    "value": {
                      "id": "hero-home",
                      "kind": "hero",
                      "title": "A clear service path",
                      "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                      "primaryAction": {
                        "label": "Contact Northstar",
                        "href": "mailto:hello@example.invalid",
                        "linkKind": "custom",
                        "targetBlank": false
                      }
                    },
                    "children": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "collections": [],
      "codeSnippets": [
        {
          "id": "metrics-snippet",
          "label": "Metrics",
          "slot": "head",
          "code": "window.metricsReady = \"draft\";",
          "enabled": false
        }
      ],
      "seo": {
        "metaTitle": "Northstar Studio | Example",
        "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
        "canonicalUrl": "https://www.example.invalid/"
      }
    },
    "currentVersionId": "pbp_op_synth_02",
    "draftPreviewToken": "draft-preview-synth-01",
    "createdAt": "2026-10-23T00:00:00.000Z",
    "updatedAt": "2026-10-23T01:00:00.000Z"
  },
  "version": {
    "id": "pbp_op_synth_02",
    "organizationId": "org-synth-01",
    "workspaceId": "workspace-synth-01",
    "siteId": "site_synth_01",
    "versionNumber": 2,
    "label": "Synthetic patch example",
    "snapshot": {
      "intent": "business_site",
      "siteTitle": "Northstar Studio",
      "siteDescription": "A fictional service studio for teams preparing a thoughtful launch.",
      "contactEmail": "hello@example.invalid",
      "navigation": [],
      "footerNavigation": [],
      "menus": [],
      "styleClasses": [
        {
          "id": "hero-corners",
          "name": "Hero corners",
          "targetKind": "hero",
          "targetScope": "section",
          "style": {
            "borderRadius": 24
          }
        }
      ],
      "theme": {
        "primary": "#111111",
        "secondary": "#333333",
        "surface": "#ffffff",
        "ink": "#111111",
        "muted": "#444444",
        "accent": "#005fcc",
        "accentSoft": "#111111",
        "glow": "#111111",
        "headingFont": "Inter, system-ui, sans-serif",
        "bodyFont": "Inter, system-ui, sans-serif",
        "radius": "16px"
      },
      "document": {
        "version": 1,
        "pages": [
          {
            "id": "page-home",
            "kind": "page",
            "pageId": "page-home",
            "label": "Home",
            "path": [
              "page-home"
            ],
            "source": {
              "kind": "page",
              "id": "page-home"
            },
            "value": {
              "id": "page-home",
              "slug": "/",
              "title": "Northstar Studio",
              "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
            },
            "children": [
              {
                "kind": "slot",
                "slotKind": "page-body",
                "id": "page-home:body",
                "pageId": "page-home",
                "label": "Page body",
                "path": [
                  "page-home",
                  "slot:body"
                ],
                "parentNodeId": "page-home",
                "source": {
                  "kind": "page",
                  "id": "page-home"
                },
                "accepts": [
                  "layout",
                  "block"
                ],
                "children": [
                  {
                    "kind": "block",
                    "id": "hero-home",
                    "pageId": "page-home",
                    "label": "A clear service path",
                    "path": [
                      "page-home",
                      "slot:body",
                      "sections:0"
                    ],
                    "source": {
                      "kind": "section",
                      "id": "hero-home"
                    },
                    "blockKind": "hero",
                    "sectionKind": "hero",
                    "sectionId": "hero-home",
                    "value": {
                      "id": "hero-home",
                      "kind": "hero",
                      "title": "A clear service path",
                      "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                      "primaryAction": {
                        "label": "Contact Northstar",
                        "href": "mailto:hello@example.invalid",
                        "linkKind": "custom",
                        "targetBlank": false
                      }
                    },
                    "children": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "collections": [],
      "codeSnippets": [
        {
          "id": "metrics-snippet",
          "label": "Metrics",
          "slot": "head",
          "code": "window.metricsReady = true;",
          "enabled": false
        }
      ],
      "seo": {
        "metaTitle": "Northstar Studio | Example",
        "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
        "canonicalUrl": "https://www.example.invalid/"
      }
    },
    "previewToken": "published_synth_02",
    "publishedAt": "2026-10-23T01:00:00.000Z"
  },
  "qualityReport": {
    "generatedAt": "2026-10-23T01:30:00.000Z",
    "score": 92,
    "issues": [
      {
        "id": "asset_library_empty",
        "severity": "info",
        "title": "No assets in the library yet",
        "detail": "Load at least a logo or hero reference so the site can move beyond pure text-only scaffolding."
      },
      {
        "id": "no_form_signal",
        "severity": "info",
        "title": "No captured form submissions yet",
        "detail": "This is normal for a fresh site, but launch monitoring should confirm the lead path is working."
      }
    ]
  },
  "urls": {
    "previewUrl": "https://runtime.example.invalid/?preview=draft-preview-synth-01",
    "publicUrl": "https://www.example.invalid"
  },
  "preview": {
    "site": {
      "id": "site_synth_01",
      "slug": "sample-site",
      "name": "Northstar Studio",
      "status": "published",
      "updatedAt": "2026-10-23T00:30:00.000Z",
      "currentVersionId": "version_synth_01",
      "draftPreviewToken": "draft-preview-synth-01"
    },
    "documentPage": {
      "id": "page-home",
      "kind": "page",
      "pageId": "page-home",
      "label": "Home",
      "path": [
        "page-home"
      ],
      "source": {
        "kind": "page",
        "id": "page-home"
      },
      "value": {
        "id": "page-home",
        "slug": "/",
        "title": "Northstar Studio",
        "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
      },
      "children": [
        {
          "kind": "slot",
          "slotKind": "page-body",
          "id": "page-home:body",
          "pageId": "page-home",
          "label": "Page body",
          "path": [
            "page-home",
            "slot:body"
          ],
          "parentNodeId": "page-home",
          "source": {
            "kind": "page",
            "id": "page-home"
          },
          "accepts": [
            "layout",
            "block"
          ],
          "children": [
            {
              "kind": "block",
              "id": "hero-home",
              "pageId": "page-home",
              "label": "A clear service path",
              "path": [
                "page-home",
                "slot:body",
                "sections:0"
              ],
              "source": {
                "kind": "section",
                "id": "hero-home"
              },
              "blockKind": "hero",
              "sectionKind": "hero",
              "sectionId": "hero-home",
              "value": {
                "id": "hero-home",
                "kind": "hero",
                "title": "A clear service path",
                "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                "primaryAction": {
                  "label": "Contact Northstar",
                  "href": "mailto:hello@example.invalid",
                  "linkKind": "custom",
                  "targetBlank": false
                }
              },
              "children": []
            }
          ]
        }
      ]
    },
    "theme": {
      "primary": "#111111",
      "secondary": "#333333",
      "surface": "#ffffff",
      "ink": "#111111",
      "muted": "#444444",
      "accent": "#005fcc",
      "accentSoft": "#111111",
      "glow": "#111111",
      "headingFont": "Inter, system-ui, sans-serif",
      "bodyFont": "Inter, system-ui, sans-serif",
      "radius": "16px"
    },
    "navigation": [],
    "footerNavigation": [],
    "menus": [],
    "styleClasses": [
      {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    ],
    "collections": [],
    "codeSnippets": [
      {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    ],
    "seo": {
      "metaTitle": "Northstar Studio | Example",
      "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
      "canonicalUrl": "https://www.example.invalid/"
    },
    "preview": true,
    "canonicalUrl": "https://sample-site.example.invalid",
    "hostname": "sample-site.example.invalid",
    "indexable": true
  },
  "idempotent": false
}

SYNTHETIC / UNRUN — identical committed replay

Same actor and exact input/key after commit; idempotent true and same version ID.

Request:

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "patch-synth-key-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

HTTP 200 response body:

{
  "site": {
    "id": "site_synth_01",
    "organizationId": "org-synth-01",
    "workspaceId": "workspace-synth-01",
    "slug": "sample-site",
    "name": "Northstar Studio",
    "status": "published",
    "brief": {
      "intent": "business_site",
      "businessName": "Northstar Studio",
      "businessType": "service",
      "audience": "fictional teams",
      "offer": "launch planning",
      "tone": "clear",
      "differentiators": [],
      "goals": []
    },
    "draftContent": {
      "intent": "business_site",
      "siteTitle": "Northstar Studio",
      "siteDescription": "A fictional service studio for teams preparing a thoughtful launch.",
      "contactEmail": "hello@example.invalid",
      "navigation": [],
      "footerNavigation": [],
      "menus": [],
      "styleClasses": [
        {
          "id": "hero-corners",
          "name": "Hero corners",
          "targetKind": "hero",
          "targetScope": "section",
          "style": {
            "borderRadius": 48
          }
        }
      ],
      "theme": {
        "primary": "#111111",
        "secondary": "#333333",
        "surface": "#ffffff",
        "ink": "#111111",
        "muted": "#444444",
        "accent": "#005fcc",
        "accentSoft": "#111111",
        "glow": "#111111",
        "headingFont": "Inter, system-ui, sans-serif",
        "bodyFont": "Inter, system-ui, sans-serif",
        "radius": "16px"
      },
      "document": {
        "version": 1,
        "pages": [
          {
            "id": "page-home",
            "kind": "page",
            "pageId": "page-home",
            "label": "Home",
            "path": [
              "page-home"
            ],
            "source": {
              "kind": "page",
              "id": "page-home"
            },
            "value": {
              "id": "page-home",
              "slug": "/",
              "title": "Northstar Studio",
              "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
            },
            "children": [
              {
                "kind": "slot",
                "slotKind": "page-body",
                "id": "page-home:body",
                "pageId": "page-home",
                "label": "Page body",
                "path": [
                  "page-home",
                  "slot:body"
                ],
                "parentNodeId": "page-home",
                "source": {
                  "kind": "page",
                  "id": "page-home"
                },
                "accepts": [
                  "layout",
                  "block"
                ],
                "children": [
                  {
                    "kind": "block",
                    "id": "hero-home",
                    "pageId": "page-home",
                    "label": "A clear service path",
                    "path": [
                      "page-home",
                      "slot:body",
                      "sections:0"
                    ],
                    "source": {
                      "kind": "section",
                      "id": "hero-home"
                    },
                    "blockKind": "hero",
                    "sectionKind": "hero",
                    "sectionId": "hero-home",
                    "value": {
                      "id": "hero-home",
                      "kind": "hero",
                      "title": "A clear service path",
                      "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                      "primaryAction": {
                        "label": "Contact Northstar",
                        "href": "mailto:hello@example.invalid",
                        "linkKind": "custom",
                        "targetBlank": false
                      }
                    },
                    "children": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "collections": [],
      "codeSnippets": [
        {
          "id": "metrics-snippet",
          "label": "Metrics",
          "slot": "head",
          "code": "window.metricsReady = \"draft\";",
          "enabled": false
        }
      ],
      "seo": {
        "metaTitle": "Northstar Studio | Example",
        "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
        "canonicalUrl": "https://www.example.invalid/"
      }
    },
    "currentVersionId": "pbp_op_synth_02",
    "draftPreviewToken": "draft-preview-synth-01",
    "createdAt": "2026-10-23T00:00:00.000Z",
    "updatedAt": "2026-10-23T01:00:00.000Z"
  },
  "version": {
    "id": "pbp_op_synth_02",
    "organizationId": "org-synth-01",
    "workspaceId": "workspace-synth-01",
    "siteId": "site_synth_01",
    "versionNumber": 2,
    "label": "Synthetic patch example",
    "snapshot": {
      "intent": "business_site",
      "siteTitle": "Northstar Studio",
      "siteDescription": "A fictional service studio for teams preparing a thoughtful launch.",
      "contactEmail": "hello@example.invalid",
      "navigation": [],
      "footerNavigation": [],
      "menus": [],
      "styleClasses": [
        {
          "id": "hero-corners",
          "name": "Hero corners",
          "targetKind": "hero",
          "targetScope": "section",
          "style": {
            "borderRadius": 24
          }
        }
      ],
      "theme": {
        "primary": "#111111",
        "secondary": "#333333",
        "surface": "#ffffff",
        "ink": "#111111",
        "muted": "#444444",
        "accent": "#005fcc",
        "accentSoft": "#111111",
        "glow": "#111111",
        "headingFont": "Inter, system-ui, sans-serif",
        "bodyFont": "Inter, system-ui, sans-serif",
        "radius": "16px"
      },
      "document": {
        "version": 1,
        "pages": [
          {
            "id": "page-home",
            "kind": "page",
            "pageId": "page-home",
            "label": "Home",
            "path": [
              "page-home"
            ],
            "source": {
              "kind": "page",
              "id": "page-home"
            },
            "value": {
              "id": "page-home",
              "slug": "/",
              "title": "Northstar Studio",
              "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
            },
            "children": [
              {
                "kind": "slot",
                "slotKind": "page-body",
                "id": "page-home:body",
                "pageId": "page-home",
                "label": "Page body",
                "path": [
                  "page-home",
                  "slot:body"
                ],
                "parentNodeId": "page-home",
                "source": {
                  "kind": "page",
                  "id": "page-home"
                },
                "accepts": [
                  "layout",
                  "block"
                ],
                "children": [
                  {
                    "kind": "block",
                    "id": "hero-home",
                    "pageId": "page-home",
                    "label": "A clear service path",
                    "path": [
                      "page-home",
                      "slot:body",
                      "sections:0"
                    ],
                    "source": {
                      "kind": "section",
                      "id": "hero-home"
                    },
                    "blockKind": "hero",
                    "sectionKind": "hero",
                    "sectionId": "hero-home",
                    "value": {
                      "id": "hero-home",
                      "kind": "hero",
                      "title": "A clear service path",
                      "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                      "primaryAction": {
                        "label": "Contact Northstar",
                        "href": "mailto:hello@example.invalid",
                        "linkKind": "custom",
                        "targetBlank": false
                      }
                    },
                    "children": []
                  }
                ]
              }
            ]
          }
        ]
      },
      "collections": [],
      "codeSnippets": [
        {
          "id": "metrics-snippet",
          "label": "Metrics",
          "slot": "head",
          "code": "window.metricsReady = true;",
          "enabled": false
        }
      ],
      "seo": {
        "metaTitle": "Northstar Studio | Example",
        "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
        "canonicalUrl": "https://www.example.invalid/"
      }
    },
    "previewToken": "published_synth_02",
    "publishedAt": "2026-10-23T01:00:00.000Z"
  },
  "qualityReport": {
    "generatedAt": "2026-10-23T01:05:00.000Z",
    "score": 92,
    "issues": [
      {
        "id": "asset_library_empty",
        "severity": "info",
        "title": "No assets in the library yet",
        "detail": "Load at least a logo or hero reference so the site can move beyond pure text-only scaffolding."
      },
      {
        "id": "no_form_signal",
        "severity": "info",
        "title": "No captured form submissions yet",
        "detail": "This is normal for a fresh site, but launch monitoring should confirm the lead path is working."
      }
    ]
  },
  "urls": {
    "previewUrl": "https://runtime.example.invalid/?preview=draft-preview-synth-01",
    "publicUrl": "https://www.example.invalid"
  },
  "preview": {
    "site": {
      "id": "site_synth_01",
      "slug": "sample-site",
      "name": "Northstar Studio",
      "status": "published",
      "updatedAt": "2026-10-23T01:00:00.000Z",
      "currentVersionId": "pbp_op_synth_02",
      "draftPreviewToken": "draft-preview-synth-01"
    },
    "documentPage": {
      "id": "page-home",
      "kind": "page",
      "pageId": "page-home",
      "label": "Home",
      "path": [
        "page-home"
      ],
      "source": {
        "kind": "page",
        "id": "page-home"
      },
      "value": {
        "id": "page-home",
        "slug": "/",
        "title": "Northstar Studio",
        "description": "A fictional service studio offering thoughtful planning and direct support for teams preparing their next launch."
      },
      "children": [
        {
          "kind": "slot",
          "slotKind": "page-body",
          "id": "page-home:body",
          "pageId": "page-home",
          "label": "Page body",
          "path": [
            "page-home",
            "slot:body"
          ],
          "parentNodeId": "page-home",
          "source": {
            "kind": "page",
            "id": "page-home"
          },
          "accepts": [
            "layout",
            "block"
          ],
          "children": [
            {
              "kind": "block",
              "id": "hero-home",
              "pageId": "page-home",
              "label": "A clear service path",
              "path": [
                "page-home",
                "slot:body",
                "sections:0"
              ],
              "source": {
                "kind": "section",
                "id": "hero-home"
              },
              "blockKind": "hero",
              "sectionKind": "hero",
              "sectionId": "hero-home",
              "value": {
                "id": "hero-home",
                "kind": "hero",
                "title": "A clear service path",
                "body": "Northstar Studio helps fictional teams plan a clear service launch with practical steps, careful review, and a direct path to a first conversation.",
                "primaryAction": {
                  "label": "Contact Northstar",
                  "href": "mailto:hello@example.invalid",
                  "linkKind": "custom",
                  "targetBlank": false
                }
              },
              "children": []
            }
          ]
        }
      ]
    },
    "theme": {
      "primary": "#111111",
      "secondary": "#333333",
      "surface": "#ffffff",
      "ink": "#111111",
      "muted": "#444444",
      "accent": "#005fcc",
      "accentSoft": "#111111",
      "glow": "#111111",
      "headingFont": "Inter, system-ui, sans-serif",
      "bodyFont": "Inter, system-ui, sans-serif",
      "radius": "16px"
    },
    "navigation": [],
    "footerNavigation": [],
    "menus": [],
    "styleClasses": [
      {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    ],
    "collections": [],
    "codeSnippets": [
      {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    ],
    "seo": {
      "metaTitle": "Northstar Studio | Example",
      "metaDescription": "A fictional service studio sharing clear launch planning, careful review, and a direct path to a first conversation for example.invalid readers.",
      "canonicalUrl": "https://www.example.invalid/"
    },
    "preview": true,
    "canonicalUrl": "https://sample-site.example.invalid",
    "hostname": "sample-site.example.invalid",
    "indexable": true
  },
  "idempotent": true
}

SYNTHETIC / UNRUN — changed request reuses committed key

Same key with a changed replacement changes the request digest.

Request:

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "patch-synth-key-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "26ac07e5dc17ef37aba9e4b73075ae58f5d7aa3b26ef1a6a642ab97f960b50c2",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = 2;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

HTTP 409 response body:

{
  "error": "idempotency_conflict"
}

SYNTHETIC / UNRUN — stale snippet preimage

Expected digest does not match the immutable baseline object.

Request:

{
  "siteId": "site_synth_01",
  "organizationId": "org-synth-01",
  "workspaceId": "workspace-synth-01",
  "expectedVersionId": "version_synth_01",
  "idempotencyKey": "patch-synth-key-001",
  "label": "Synthetic patch example",
  "snippetPatches": [
    {
      "id": "metrics-snippet",
      "expectedSha256": "0000000000000000000000000000000000000000000000000000000000000000",
      "replacement": {
        "id": "metrics-snippet",
        "label": "Metrics",
        "slot": "head",
        "code": "window.metricsReady = true;",
        "enabled": false
      }
    }
  ],
  "styleClassPatches": [
    {
      "id": "hero-corners",
      "expectedSha256": "a2165c725e69778aa4cfcc63620933705d1c8223fc8b913c15e5ed27cd2f7282",
      "replacement": {
        "id": "hero-corners",
        "name": "Hero corners",
        "targetKind": "hero",
        "targetScope": "section",
        "style": {
          "borderRadius": 24
        }
      }
    }
  ]
}

HTTP 409 response body:

{
  "error": "preimage_changed"
}

Change log

2026-10-23: Documented the current published-baseline patch contract, exact source error distinctions and complete synthetic worked request/response cases. No site operation was executed for these examples.