Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshqu.com/llms.txt

Use this file to discover all available pages before exploring further.

Every policy in MeshQu has a version history. Only one version is ever live at a time, and changes flow through an explicit lifecycle with optional maker-checker review. This page describes the states a version can be in, the actions each one allows, and how the API surfaces both to clients.

​
Version states

At any moment, the version you are looking at is in exactly one of four states.
StateMeaning
activeThe version currently used to evaluate incoming decisions.
draftA working copy being authored. Not yet used for evaluation. At most one draft exists per policy.
submittedA draft that has been handed off for approval. Editing is paused; only the approver can act.
historicalA previously active version. Read-only. Retained for audit and diff.
Clients select the state they want to look at through a URL parameter on the policy detail endpoint: 
GET /v1/policies/:id?version=active          # default
GET /v1/policies/:id?version=draft           # 404 NOT_FOUND if no draft exists
GET /v1/policies/:id?version=<number>        # a specific historical or the active version
The response always resolves selectedVersion to the numeric version and reports the corresponding versionState.
Only the active version is used during evaluation. Looking at a draft or historical version never changes what MeshQu actually decides for production traffic.

​
Maker-checker

MeshQu tenants can enable maker-checker enforcement to require that a different person approves a draft than the one who created it.
  • The maker authored the draft.
  • The checker approves or rejects it.
  • The same user cannot be both on the same draft when maker-checker is enabled.
The check is enforced server-side on the ratify endpoint. When maker-checker is on, a ratify request from the draft’s author returns 403 MAKER_CHECKER_VIOLATION regardless of what the UI shows. When maker-checker is disabled, the author can ratify their own draft.

​
Lifecycle transitions

Active ──Start editing──▶ Draft ──Submit──▶ Submitted ──Approve──▶ Active (new v{n+1})
                            │                   │
                            │ Discard           │ Reject + reason
                            ▼                   ▼
                        (removed)            Draft (with reason attached)
  • Start editing — creates a new draft from the active version. Only one draft per policy at a time.
  • Submit — moves a draft into the submitted state for a checker. Available in a future release.
  • Approve (ratify) — ratifies the submitted draft. It becomes the new active version; the previous active becomes historical.
  • Reject — returns a submitted draft to draft with a rejection reason attached. Available in a future release.
  • Discard — deletes the draft. Does not affect the active version.
  • Create draft from v — copies a historical version into a new draft. Useful for reverting.

​
How permissions are returned

Rather than ask the client to re-derive what a user can do, the policy detail response carries two fields that answer this directly. permissions — a boolean record: 
{
  "permissions": {
    "canEdit": true,
    "canSubmit": false,
    "canApprove": false,
    "canReject": false,
    "canDiscard": true,
    "canRestore": false,
    "canCompare": true
  }
}
Flags reflect the authenticated actor’s effective rights against the selected version under the current tenant settings. Use them to gate fine-grained UI (for example, showing a confirm dialog on canDiscard). actions — an ordered array of lifecycle actions the UI should surface: 
{
  "actions": [
    { "kind": "continue_editing", "label": "Continue editing" },
    { "kind": "discard",          "label": "Discard draft" },
    { "kind": "compare",          "label": "Compare…" }
  ]
}
This array is the single source of truth for which buttons to render. Unavailable actions are omitted, not disabled. Clients must not invent extra actions from the permissions record — if an action is absent from actions, the server does not authorise it.

​
Action kinds

KindPurpose
start_editingCreate a new draft from the active version.
continue_editingResume editing an existing draft you authored.
continue_reviewingRead a draft authored by someone else.
submitHand the draft off for approval. Gated — see below.
recallWithdraw your own submitted draft back to draft state. Gated.
approveRatify a submitted draft authored by someone else. Gated.
rejectReturn a submitted draft to draft with a reason. Gated.
discardDelete the current draft.
restoreCreate a new draft from a historical version. Label: "Create draft from v{n}".
compareOpen the diff view against another version.
submit, recall, approve, and reject are part of the type contract but are not emitted by the current API. They become available once the submit/reject endpoints ship. Clients built today against actions[] will render them automatically when the server starts returning them — no code change needed.

​
Action matrix

For a given version state, authored-by relationship, and role, the server emits a specific ordered set of actions. The table lists what is emitted today; entries in italics will be added in a future release.
Version stateActor roleActions emitted today
activewrite-capablestart_editing, compare
activeread-onlycompare
draft — authorwrite-capablecontinue_editing, discard, compare (+ submit)
draft — non-authorwrite-capablecontinue_reviewing, compare
submitted — authorwrite-capablecompare (+ recall)
submitted — non-authorwrite-capablecompare (+ approve, reject)
historicalwrite-capablecompare, restore
historicalread-onlycompare
When maker-checker is disabled, the “non-author vs author” distinction stops mattering for approve — the author can ratify their own draft.

​
Errors

  • 404 NOT_FOUND — the policy, the requested ?version= number, or the requested ?version=draft does not exist. The response message distinguishes the case ("Policy not found", "Draft version not found", etc.) but the code is always NOT_FOUND for client convenience.
  • 403 MAKER_CHECKER_VIOLATION — returned by the ratify endpoint when maker-checker is enabled and the actor is the draft author.

​
Why the server owns this

Policy governance is a compliance surface. Emitting permissions and actions[] from the server means:
  1. The UI cannot accidentally show a button whose action the server would refuse.
  2. Clients do not need to re-implement role resolution, tenant-settings lookup, or the action matrix.
  3. New action kinds (like submit or reject) can roll out server-side and become visible in existing clients without a coordinated release.
See the API Reference for the full policy detail response shape.