Sign In

Govern WordPress Layouts with Structure Contracts

A Structure Contract turns a Blueprint's intended Gutenberg layout into a server-enforced document model. It lets an agent address meaningful fields such as hero.title or body.additional without receiving a fragile serialized block path or permission to rebuild the page.

Editor locks improve the authoring experience, but they are not the security boundary. Composer checks the Structure Contract again on REST, native editor, and MCP writes. A client cannot bypass it by sending raw block markup.

Ownership model​

Every declared node has one owner:

  • Blueprint-owned structure defines required containers, order, block type, and protected presentation. Agents and ordinary editors cannot remove or replace it through a raw write.
  • Instance-owned content is the text, media, or approved attribute that may vary in each post. Composer edits it through a stable semantic ID.
  • User-owned slot content is editorial freedom inside a declared extension slot. The slot fixes allowed block types and minimum/maximum cardinality; approved children remain insertable, editable, movable, and removable.

This separation preserves design intent without freezing every word or denying editors controlled local additions.

Stable semantic IDs​

A semantic ID is durable policy, not a generated array index. Use names that describe the role of the content, for example:

hero
hero.title
body
body.text
body.additional

Changing an ID is a contract migration. Do not encode a theme version, database ID, environment name, or current block position into it.

Extension slots​

An extension slot declares:

  • its semantic ID and parent;
  • allowed direct block types;
  • minimum and maximum direct children;
  • whether the region is required;
  • editor locking and appender behavior.

Composer exposes semantic insert, update, move, and remove operations. It assigns a stable user-owned identity to every inserted tree and validates the complete document after each change. A cardinality or allowlist failure is atomic: the draft is not partially saved.

Synchronized structural patterns​

Store reusable structure in a published WordPress wp_block synchronized pattern. The post keeps a native locked core/block reference rather than a copied block tree.

Use native Pattern Overrides for declared instance fields. Composer stores extension-slot children on the post's pattern instance, not in the shared wp_block. Editing one post therefore cannot modify every page that uses the pattern.

A Site Contract must identify each governed synchronized pattern, its local wp_block record, version, override bindings, and compatible Structure Contract. Theme & providers reports a missing source only when that source kind is relevant and actually unavailable.

Native WordPress creation​

The Site Contract can set each supported post type to:

  • off: WordPress Add New remains unmanaged;
  • optional: an administrator may choose a compatible Blueprint;
  • required: Add New must initialize a managed document from the configured default Blueprint.

The native document receives the same Blueprint, synchronized patterns, Structure Contract, baseline, language, and server-side save protection as an agent-created draft. It does not become agent-owned merely because it is managed.

Pattern evolution and reconciliation​

A compatible shared-pattern revision may change protected presentation while retaining every required semantic field and slot. Existing Pattern Overrides and user-owned slot children remain attached to their instances.

If a revision removes or changes a required binding, Composer reports an explicit invalid or reconciliation-required state. It does not silently rewrite stored posts or discard content.

For a versioned contract change:

  1. clone the active Config Set;
  2. register the successor Structure Contract and Blueprint;
  3. define an exact source-to-target migration;
  4. preview the result without writing;
  5. classify automatic and review-required items;
  6. create revision-bound update proposals for reviewed items;
  7. let a human merge accepted proposals.

Bulk planning is bounded and proposal creation is explicit. Composer never turns a migration into automatic bulk publication.

Theme and provider responsibilities​

The theme owns templates, synchronized patterns, markup, styles, and theme.json tokens. A provider owns the schema and materializer for its custom components. Composer owns the semantic contract, validation, governed mutation, reconciliation state, proposals, and audit trail.

AI Kit Knowledge Base sections may act as semantic containers for governed native Gutenberg or Agent Canvas descendants. AI Kit Feature and Doc Search components retain their stricter child validation.

Acceptance checklist​

  • Every semantic ID is stable and unique.
  • Every required field or slot resolves exactly once after pattern expansion.
  • Every allowed block is registered and validated.
  • Slot minimum and maximum values match the intended editorial freedom.
  • Pattern Overrides cover every declared instance field.
  • Instance slot content does not change the shared wp_block.
  • Native Add New, MCP editing, preview, proposal, and reconciliation paths are tested with the active theme.
  • Published changes remain proposal-driven and human-approved.

Continue with Configuration and lifecycle, Theme integration, and MCP Access and OAuth.