Kugel Platform

Chapter 1

The content model: everything is a governed object

Content truth lives in a per-tenant object store, not in files. This chapter covers what an object is, how it is changed, and where the line between publishing and releasing sits.

Back to the tour

What a governed object is

A governed object is a record with a stable id, a type (page, article, theme, navigation and others), a body, and a history. Every change adds a history entry, and entries are never pruned.

Two counters track change. version moves on every write, including locks and publishes. content_revision moves only when the content itself changes. Approvals pin a content revision, so approving a page approves exactly what was read.

Pages are built from named sections. Sections carry stable ids, which is what lets tracking and experiments follow a piece of content across edits.

Object verbs

The only way to change content

  1. 1

    Check out

    Take a lock on one object. You receive a lock token and the current record version.

  2. 2

    Patch

    Send typed operations with the token and the version you last read. A stale version or a missing lock is refused.

  3. 3

    Validate

    A dry run applies the same checks as a real write and persists nothing. Use it before patching.

  4. 4

    Publish

    Export the object to git. This keeps your lock on purpose, so concurrent changes are caught.

  5. 5

    Check in

    Release the lock. If you skip this, the object stays locked to everyone else until the lease ends.

Locks and conflicts

What the system refuses, and why

A lock lease lasts 15 minutes by default and can be set up to one hour.

Error 423 means you hold no valid lock: check out again.

Error 409 means your record version is stale: read again, then retry.

An invalid resulting body fails with 422 and nothing is written.

A retry after a timeout reuses the same idempotency key and returns the original result, not a duplicate.

Public and private

Private fields never reach readers

Objects can carry private fields, such as strategy notes and intent. They stay in the store.

They are stripped when the reader copy is built, the renderer emits only public fields of public content, and the validator checks the reader copy as well. Credentials and review notes are kept out of reader-visible text for the same reason.

See how pages render
A sample document image served from the platform image path

Publish is not release

Publish commits a JSON export to git with a marker that skips the build. It is dark: nothing on the live site changes.

Release is a separate action that starts one production build, which ships every export accumulated since the last release. A deploy status check then confirms what production serves.

So a successful publish proves the export exists. It does not prove a reader can see the change.

Status

What is established

Verified live
Object verbs, locks and revisions

Used to write this page

Verified live
Dark publish, then separate release

Two distinct steps

Verified live
Private fields stay in the store

Checked at build and validation

Questions

Can an agent edit content by changing files?

No. Exports in git are generated output. Governed changes go through object verbs.

Why two counters?

Locking and publishing should not look like content changes. Only content_revision tells you the words or layout moved.

Keep going