apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-21 02:28:07 +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

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