apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-07-12 03:12:11 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add cluster JSON state ledger status

Browse source
This commit is contained in:
aaltshuler 2026-06-08 21:09:23 +03:00
parent 043b02e617
commit a7956ea5a9
8 changed files with 925 additions and 76 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/user/cluster-config.md
View file

@ -1,17 +1,19 @@
# Cluster Config
**Status:** Stage 1 read-only preview.
**Status:** Stage 2A read-only preview.
Cluster config is the future control-plane configuration surface for a whole
OmniGraph deployment. In this stage, OmniGraph can validate a local
`cluster.yaml` folder and produce a deterministic read-only plan. It does not
apply changes, acquire locks, open graph roots, start servers, or write state.
`cluster.yaml` folder, produce a deterministic read-only plan, and inspect the
local JSON state ledger. It does not apply changes, open graph roots, scan live
cluster state, start servers, or write graph resources.
## Commands
```bash
omnigraph cluster validate --config ./company-brain
omnigraph cluster plan --config ./company-brain --json
omnigraph cluster status --config ./company-brain --json
```
`--config` points at a directory, not a file. The directory must contain
@ -19,7 +21,7 @@ omnigraph cluster plan --config ./company-brain --json
## Supported `cluster.yaml`
Stage 1 accepts only the read-only resource subset:
Stage 2A accepts only the read-only resource subset:
```yaml
version: 1
@ -43,10 +45,12 @@ policies:
applies_to: [knowledge]
```
`metadata.name` is a display label. `state.lock` is parsed for forward
compatibility, but no lock is acquired in this read-only stage. `state.backend`
may be omitted or set to `cluster`; external state backends are reserved for a
later stage.
`metadata.name` is a display label. `state.backend` may be omitted or set to
`cluster`; external state backends are reserved for a later stage. `state.lock`
defaults to `true`. When enabled, `cluster plan` briefly acquires
`<config-dir>/__cluster/lock.json` while it reads state, then removes it before
returning. `cluster status` never acquires the lock; it only reports whether one
is present.
## Validation
@ -78,6 +82,7 @@ resource is planned as a create. If present, the file must use this shape:
```json
{
"version": 1,
"state_revision": 0,
"applied_revision": {
"config_digest": "...",
"resources": {
@ -86,10 +91,34 @@ resource is planned as a create. If present, the file must use this shape:
"query.knowledge.find_experts": { "digest": "..." },
"policy.base": { "digest": "..." }
}
}
},
"resource_statuses": {
"graph.knowledge": {
"status": "applied",
"conditions": [],
"message": "optional status detail"
}
},
"approval_records": {},
"recovery_records": {},
"observations": {}
}
```
`state_revision`, `resource_statuses`, `approval_records`, `recovery_records`,
and `observations` are optional so older Stage 1 state fixtures keep working.
Missing `state_revision` is treated as `0`. Resource status values are
`pending`, `planned`, `applying`, `applied`, `drifted`, `blocked`, or `error`.
Plan output compares desired resource digests against state resource digests
and reports `create`, `update`, and `delete` changes. The command never writes
`state.json`; apply and locking are later-stage work.
and reports `create`, `update`, and `delete` changes. It also reports the state
CAS (`sha256:<digest>`), state revision, and lock id used for the read. The
command never writes `state.json`; apply, refresh, import, and live drift scans
are later-stage work.
## Status
`cluster status` reads the same local JSON state ledger and prints what the
ledger says is deployed. It does not validate referenced schema/query/policy
files and does not inspect live graphs. Missing `state.json` succeeds with a
warning; invalid state JSON or an unsupported state version fails.