Branches & proposals

The ontology schema is versioned. There is one canonical published baseline — main — and every edit happens on a proposal branch that gets reviewed before it merges.

Why versioned

The schema is consumed by workflows, agents, the graph view, the analyst, and any custom UI. A schema change that breaks a workflow's expected property type is exactly the kind of change you want to see in review before it ships. Proposals give you that review without slowing down day-to-day work.

main

main is the published baseline. From the workbench:

• main appears in the branch picker as the default.
• main is read-only. You can browse, search, traverse — you cannot edit.
• Every consumer (workflow tools, graph view, analyst) reads from main by default.

Proposals

A proposal is a branch off main with a name like proposal/add-customer-tier or proposal/rename-account-status. Proposals can:

• Add new object types, link types, action types, bindings.
• Modify existing types (change a property type, add a property, change identity rules).
• Remove types (with a migration path).
• Update bindings (re-map columns, switch source tables).

The workbench shows the diff between the proposal and main. A reviewer can see exactly which types changed and how.

Lifecycle

   ┌─────────┐    propose    ┌──────────────┐
   │  main   │ ─────────────▶│   proposal   │
   └─────────┘                └──────────────┘
        ▲                             │
        │ publish (replaces main)     │ review
        └─────────────────────────────┘
                                     │
                                     ▼ archive (discarded)
                                  [end]

What "publish" does

Publishing a proposal:

1. Validates the proposal against the current main — flags conflicts.
2. Atomically replaces main's baseline with the proposal's baseline.
3. Re-issues the version stamp on every binding, action type, and object type.
4. Emits a structured event for downstream consumers.
5. Records an audit event with the actor, the proposal, and the published changes.

After publish, the proposal branch is closed. Future edits start from the new main.

What "archive" does

Archiving a proposal:

1. Marks the proposal as archived in the catalog.
2. Removes it from the active branch picker.
3. Records an audit event.

Archived proposals are kept for compliance but don't appear in normal browsing. They can be restored — useful when a proposal was archived in error.

Concurrent edits

Multiple proposals can be in flight at the same time. The publish step does a conflict check — if a second proposal touches a type that a first proposal already published, the second proposal's reviewer sees the conflict and decides how to resolve it.

Authorisation

Related

• Concepts → Branches — where branches fit in the five layers.
• Audit logging — every publish and archive is logged.
• Authoring SDK → Ontologies — packs ship on main by default; pack updates land via proposals.