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

Andrew Altshuler 77dffdae92

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

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>

2026-06-14 14:39:25 +03:00

2.9 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.

What's shipped

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.

What's not shipped yet

Severity configuration (planned: lint: { OG-DS-103: error }).
@allow(OG-XXX-NNN, "rationale") suppression directives.
Pre-migration checks (the migration_check { … } block).
The CD / VE / LK / NM families.
CI integration.
Cost-class annotations.

Code catalog

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
`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

Families

The ten chassis families:

Prefix	Family	Status
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	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

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

2.9 KiB Raw Blame History