apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-15 01:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(user): de-dev polish — strip internal scaffolding from user docs (Phase 3a) (#226)

Browse source 
Remove developer-only scaffolding that leaked into the public user/operator
docs, while preserving every user-facing behavior, command, flag, endpoint,
constant, and env var. No behavior changes.

Removed across 18 files:
- internal ticket / sequencing refs (MR-NNN, RFC-NNN, "Phase N");
- source-code paths (crates/**/*.rs, *.pest) and internal struct/function
  dumps (e.g. the QueryIR / GraphCommit / SchemaMigrationPlan Rust types,
  internal fn names like fork_branch_from_state, optimize_all_tables);
- Lance-internal blocker prose (upstream issue numbers, blob-decode cause,
  sidecar Phase-B/C mechanics) — keeping the user-visible behavior (e.g.
  "optimize skips Blob-column tables; reads/writes unaffected");
- pre-v0.4.0 Run-state-machine archaeology.

Internal IR/lowering/recovery-internals sections were either trimmed to a
brief user-facing note (e.g. "Traversal execution", "interrupted writes
recover automatically; recovery commits are recorded under actor
omnigraph:recovery") or removed.

Kept: all language syntax, lint codes, Cedar actions/scopes, endpoints,
error taxonomy, every constant and env var (verified none dropped from the
constants cheat-sheet), and the operator-facing explanations of on-disk
artifacts. Residual "legacy" mentions are all user-facing (the deprecated
omnigraph.yaml, the legacy token chain, old command names).

Verified: zero internal-scaffolding leaks (MR/RFC/Phase/.rs/.pest = 0) across
docs/user; zero broken links; check-agents-md.sh green.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Andrew Altshuler 2026-06-14 14:39:25 +03:00 • committed by GitHub
parent 612741b387
commit 77dffdae92
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 192 additions and 266 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/user/schema/index.md
View file

@ -1,7 +1,5 @@
# Schema Language (`.pg`)
Pest grammar at `crates/omnigraph-compiler/src/schema/schema.pest`. AST at `schema/ast.rs`. Catalog at `catalog/mod.rs`.
## Top-level declarations
- `interface <Name> { property* }` — reusable property contracts.
@ -47,37 +45,28 @@ Edge bodies only allow `@unique` and `@index`.
- `@<ident>` or `@<ident>(<literal>)` on any declaration or property.
- Known annotations:
- `@embed` on a Vector property — names the *source* property whose text gets embedded into this vector at ingest (`embed_sources` map in NodeType).
- `@embed` on a Vector property — names the *source* property whose text gets embedded into this vector at ingest.
- `@description("…")`, `@instruction("…")` on query declarations (carried through to clients).
- Custom annotations are accepted by the parser and surfaced in catalog metadata; unrecognized annotations don't fail compilation.
## Catalog construction
## Table layout
- Pass 0: collect interfaces.
- Pass 1: collect nodes, expand `implements`, build constraint and `@embed` mappings, build the Arrow schema for each node table (`id: Utf8` plus all properties; blob columns get `LargeBinary`).
- Pass 2: collect edges, validate that `from_type` / `to_type` exist, normalize edge names case-insensitively for lookup, validate constraints for edges. Edge Arrow schema: `id: Utf8, src: Utf8, dst: Utf8` plus edge properties.
## Schema IR & stable type IDs
- `SCHEMA_IR_VERSION = 1` (`catalog/schema_ir.rs`).
- Each interface/node/edge currently gets a `stable_type_id` from a kind+name hash.
- Rename-preserving accepted IDs are an architectural invariant, but the current hash-on-name implementation is a known gap until migration carries IDs across `@rename_from`.
- Serialized as JSON for diff/migration plans.
- Each node type compiles to a table with an `id: Utf8` column plus all declared properties (blob columns are stored as `LargeBinary`); `implements` clauses expand the interface's properties into the node.
- Each edge type compiles to a table with `id: Utf8, src: Utf8, dst: Utf8` plus the edge's own properties. Edge endpoint types (`from`/`to`) must exist, and edge names are matched case-insensitively.
## Schema migration planning
`plan_schema_migration(accepted, desired) -> SchemaMigrationPlan { supported, steps[] }` with step types:
A migration plan compares the accepted schema against the desired one and reports whether the change is supported plus the ordered steps it requires:
- `AddType { type_kind, name }`
- `RenameType { type_kind, from, to }`
- `AddProperty { type_kind, type_name, property_name, property_type }`
- `RenameProperty { type_kind, type_name, from, to }`
- `AddConstraint { type_kind, type_name, constraint }`
- `UpdateTypeMetadata { … annotations }`
- `UpdatePropertyMetadata { … annotations }`
- `UnsupportedChange { entity, reason }` (forces `supported=false`)
- Add a type
- Rename a type
- Add a property
- Rename a property
- Add a constraint
- Update type or property metadata (annotations)
- Unsupported change (reports the entity and reason; forces the plan to unsupported)
`apply_schema()` returns `SchemaApplyResult { supported, applied, manifest_version, steps }` and is gated by an internal `__schema_apply_lock__` system branch so concurrent schema applies serialize.
Applying a plan reports whether it was supported, the steps applied, and the resulting manifest version. Concurrent schema applies serialize so they can't interleave.
## Destructive drops — `--allow-data-loss`

43
docs/user/schema/lint.md
View file

@ -2,29 +2,26 @@
The migration planner emits **code-tagged diagnostics** for every schema change it rejects. Codes have the form `OG-XXX-NNN` and identify the rule (not the message); operators reference them in suppression directives, severity overrides, and CI reports.
This page is the catalog of codes shipped today. The chassis behind it is tracked in [MR-694](https://linear.app/modernrelay/issue/MR-694).
This page is the catalog of codes shipped today.
## What's shipped in v0
## What's shipped
- Stable code attached to every rejection the planner emits (today: 5 of 17 paths — the rest carry `code: None` and are tagged as future work).
- Stable code attached to every rejection the planner emits (today: 5 of 17 paths — the rest are tagged as future work).
- Code appears in the user-visible error message: `[OG-DS-104] removing property 'Person.age' is not supported …`.
- CLI `omnigraph schema plan` shows the code on `unsupported change …` lines.
- Tests in `tests/schema_apply.rs` assert on codes, not on free-text prose.
## What's not shipped yet
- Severity configuration in `omnigraph.yaml` (planned: `lint: { OG-DS-103: error }`).
- Severity configuration (planned: `lint: { OG-DS-103: error }`).
- `@allow(OG-XXX-NNN, "rationale")` suppression directives.
- Pre-migration checks (the `migration_check { … }` block — MR-941).
- The CD / VE / LK / NM families (MR-942..945).
- CI integration (MR-946).
- Cost-class annotations (MR-944).
- Pre-migration checks (the `migration_check { … }` block).
- The CD / VE / LK / NM families.
- CI integration.
- Cost-class annotations.
See the parent chassis issue (MR-694) for the design and the per-family sub-issues for what's planned.
## Code catalog
## Code catalog (v0)
The chassis defines ten families. Today only DS and MF have emitted codes. The remaining families are reserved for future PRs.
The chassis defines ten families. Today only DS and MF have emitted codes. The remaining families are reserved for future releases.
| Code | Family | Tier | Default severity | Meaning |
|---|---|---|---|---|
@ -37,24 +34,22 @@ The chassis defines ten families. Today only DS and MF have emitted codes. The r
| `OG-MF-104` | Maybe-fail | validated | error | tighten nullable to non-nullable (reserved) |
| `OG-MF-106` | Maybe-fail | destructive | error | narrowing scalar type |
The full code catalog source of truth lives in `crates/omnigraph-compiler/src/lint/codes.rs`. CI-level invariants (uniqueness, format, family coverage) are unit-tested in the same module.
## Families
The ten chassis families:
| Prefix | Family | Status |
|---|---|---|
| **DS** | Destructive (data-loss) | shipped, v0 |
| **MF** | Maybe-fail / data-dependent | shipped, v0 |
| **CD** | Constraint deletion (relaxation warning) | tracked in MR-942 |
| **DS** | Destructive (data-loss) | shipped |
| **MF** | Maybe-fail / data-dependent | shipped |
| **CD** | Constraint deletion (relaxation warning) | planned |
| **BC** | Backward-incompatible (rename) | implicit in `@rename_from`; codify later |
| **NM** | Naming conventions | tracked in MR-945 |
| **OW** | Ownership (per-resource Cedar) | tracked in MR-722 |
| **NL** | Non-linear (branch-merge divergence) | stubbed in MR-947 |
| **VE** | Vector / embedding | tracked in MR-943 |
| **ED** | Edge / graph topology | tracked in MR-701, MR-943 |
| **LK** | Lock duration / cost | tracked in MR-944 |
| **NM** | Naming conventions | planned |
| **OW** | Ownership (per-resource Cedar) | planned |
| **NL** | Non-linear (branch-merge divergence) | planned |
| **VE** | Vector / embedding | planned |
| **ED** | Edge / graph topology | planned |
| **LK** | Lock duration / cost | planned |
## Prior art