mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-15 01:55:13 +02:00

Andrew Altshuler d46e50dd6d

docs(user): restructure user docs into topic sections (Phase 1) (#223 )

Move the 23 flat docs/user/*.md files into topic subdirectories so the
user guide is organized by area (schema, queries, search, branching, cli,
operations, clusters, concepts, reference) instead of a flat list. This is
a pure structural move — whole files relocated, every cross-doc link
recomputed, no prose rewrites or content splits (those follow in Phase 2).

- 19 `git mv`s (install.md, deployment.md stay top-level); history preserved
  (renames detected at 92–100% similarity).
- All intra-doc links, AGENTS.md's topic table (52 pointers), and the
  docs/dev + docs/releases back-links recomputed via relpath from each
  file's new location.
- docs/user/index.md rewritten as a sectioned nav hub.
- Fixed 5 doc-path references in Rust (comments + two user-facing server
  settings error strings) to point at the new locations.

Verified: zero broken .md links across tracked docs; check-agents-md.sh
green (with the untracked scratch docs set aside); touched crates build.

Note: the public site (omnigraph-web) imports docs/ via a flat-only script;
its import-docs.mjs needs a subdir-aware update before the next re-sync.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-14 13:52:14 +03:00

3.5 KiB

Raw Blame History

Schema lint

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.

What's shipped in v0

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).
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 }).
@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).

See the parent chassis issue (MR-694) for the design and the per-family sub-issues for what's planned.

Code catalog (v0)

The chassis defines ten families. Today only DS and MF have emitted codes. The remaining families are reserved for future PRs.

Code	Family	Tier	Default severity	Meaning
`OG-DS-101`	Destructive	destructive	error	drop graph type with rows (reserved; not yet emitted)
`OG-DS-102`	Destructive	destructive	error	drop node type with rows
`OG-DS-103`	Destructive	destructive	error	drop edge type with rows
`OG-DS-104`	Destructive	destructive	error	drop property with rows
`OG-DS-105`	Destructive	destructive	error	drop populated vector column (reserved)
`OG-MF-103`	Maybe-fail	validated	error	add required property without `@default` to populated type
`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
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

Prior art

The chassis is modeled on Atlas's sqlcheck analyzers (DS / MF / CD / BC / NM families). Atlas was the direct inspiration for stable codes, per-rule severity, suppression directives with rationale, and pre-migration checks. omnigraph adapts the chassis to a typed-IR substrate (no SQL injection vector, no per-engine locking, native vector / edge / embedding types Atlas doesn't have).

3.5 KiB Raw Blame History