diff --git a/crates/ogar-adapter-surrealql/Cargo.toml b/crates/ogar-adapter-surrealql/Cargo.toml index 9cb1ecc..38f397d 100644 --- a/crates/ogar-adapter-surrealql/Cargo.toml +++ b/crates/ogar-adapter-surrealql/Cargo.toml @@ -6,7 +6,7 @@ license.workspace = true repository.workspace = true authors.workspace = true rust-version.workspace = true -description = "Bidirectional SurrealQL DDL bridge for OGAR. emit(Class) -> SurrealQL DDL via a hand-written formatter aligned with surrealdb-core::catalog::TableDefinition::new_for_ddl (Sprint C16b); unmap(SurrealQL) -> Class via surrealdb-parser + AST walk. Sources the knowable_from clock for lance-graph-planner::temporal::classify (per OPENPROJECT-TRANSCODING.md §10.3)." +description = "DEPRECATED (2026-07-22, SoC ruling): OGAR does not delegate its AST/IR concern to SurrealQL's AST (DLL) API — even if functional it is a separation-of-concerns error. DO arm = ActionDef via ogar-render-askama, spine = compiled ClassView (V3). See docs/DISCOVERY-MAP.md D-SURREALQL-DEPRECATED. [Historical: bidirectional SurrealQL DDL bridge — emit(Class) -> DDL, unmap(DDL) -> Class.]" [features] default = [] diff --git a/crates/ogar-adapter-surrealql/src/lib.rs b/crates/ogar-adapter-surrealql/src/lib.rs index 725f1e7..807e86f 100644 --- a/crates/ogar-adapter-surrealql/src/lib.rs +++ b/crates/ogar-adapter-surrealql/src/lib.rs @@ -1,5 +1,44 @@ //! `ogar-adapter-surrealql` — bidirectional SurrealQL DDL bridge for OGAR. //! +//! # ⊘ DEPRECATED (operator ruling 2026-07-22 — a separation-of-concerns error) +//! +//! **This whole crate is deprecated.** The reason is *not* primarily "it +//! touches storage" — it is the **initial separation-of-concerns +//! misconception the crate embodies: that OGAR's own runtime AST / IR concern +//! could be delegated to SurrealQL's AST (DLL) API.** OGAR is a compiler; its +//! IR (`Class` / `ActionDef`) is *its own* concern. A source is lifted into +//! `Class` by OGAR's own front-ends (`ogar-from-`), **never** by +//! round-tripping through a foreign query language's AST parser +//! (`parse_surrealql_ddl` is built on `surrealdb-parser` / `surrealdb-ast` — +//! that IS the delegation). Symmetrically, SurrealQL DDL is at most a pure +//! adapter *output* — never a spine, never part of OGAR's AST pipeline. +//! +//! **Even if it worked perfectly, it would still be wrong** — this is an +//! architectural (SoC) error, not a functional one. (Consequences that also +//! hold, but are downstream of the SoC point, not the root: no runtime +//! (de)serialization of code; compile-time only; the Firewall ADR-022/023.) +//! +//! The behavioral (DO) arm can **never** live in SurrealQL — behavior is +//! `ActionDef`, resolved at compile time. The sanctioned replacements, all +//! compile-time: +//! +//! - **Behavior → Rust methods, not DDL:** +//! [`ogar_render_askama::render_class_with_methods`] emits a struct whose +//! methods ARE the `ActionDef` DO-arm (`on_enter` ⇒ `&mut self`). Compiled, +//! not parsed. +//! - **Spine → the compiled `ClassView`** baked into the binary via the +//! lance-graph⟷OGAR V3 substrate (`lance_graph_contract::facet`). Compiled +//! beats parsed; even a JIT over SurrealQL loses to compiled code. +//! - **Structural egress** (if a storage membrane genuinely needs a schema +//! language) stays on the sibling RDF/columnar adapters — those are storage +//! membranes, not a spine, and are out of scope for this deprecation. +//! +//! This supersedes the 2026-06-04 `docs/SURREAL-AST-AS-ADAPTER.md §7` "No +//! deprecation" line (see that doc's dated correction and +//! `docs/DISCOVERY-MAP.md` `D-SURREALQL-DEPRECATED`). The crate is retained, +//! `#[deprecated]`-annotated, for the one default-off caller and for +//! reference; it is not a forward path. +//! //! # The two directions //! //! Per `docs/OGAR-AST-CONTRACT.md §2`: @@ -78,6 +117,14 @@ #![forbid(unsafe_code)] #![warn(missing_docs)] +// This crate is deprecated (SoC ruling 2026-07-22 — see the module banner: +// OGAR's AST/IR is not delegated to SurrealQL's AST API). Its own public fns +// / `ParseError` are `#[deprecated]`, and +// they reference each other internally (the fn signatures + bodies + the +// crate's own tests). `#![allow(deprecated)]` silences only THIS crate's +// internal use so it still compiles + its tests still prove the retained +// behavior; EXTERNAL callers still receive the deprecation warning. +#![allow(deprecated)] use ogar_vocab::{Association, AssociationKind, Attribute, Class, EnumDecl}; @@ -98,6 +145,9 @@ use ogar_vocab::{Association, AssociationKind, Attribute, Class, EnumDecl}; /// to call catalog builders directly once the rust-version blocker /// clears. #[must_use] +#[deprecated( + note = "SoC ruling 2026-07-22: OGAR's IR is OGAR's own concern; SurrealQL DDL is at most a pure adapter output, never a spine or part of OGAR's AST pipeline. DO arm = ActionDef via ogar_render_askama::render_class_with_methods; spine = compiled ClassView (V3). See docs/DISCOVERY-MAP.md D-SURREALQL-DEPRECATED." +)] pub fn emit_surrealql_ddl(classes: &[Class]) -> String { let mut out = String::new(); for class in classes { @@ -141,6 +191,9 @@ pub fn emit_surrealql_ddl(classes: &[Class]) -> String { /// `parse_surrealql_ddl(emit_surrealql_ddl(parse_surrealql_ddl(x)?)?) == parse_surrealql_ddl(x)?` /// should hold for any well-formed SurrealQL DDL `x`. Proptest fixture /// lands alongside the parser wiring. +#[deprecated( + note = "SoC ruling 2026-07-22: delegating OGAR's runtime AST/IR concern to SurrealQL's AST (DLL) API (surrealdb-parser/surrealdb-ast) is a fundamental separation-of-concerns error, even if functional. Sources lift into Class via OGAR's own ogar-from- front-ends, never a foreign-AST round-trip. See docs/DISCOVERY-MAP.md D-SURREALQL-DEPRECATED." +)] pub fn parse_surrealql_ddl(_input: &str) -> Result, ParseError> { #[cfg(feature = "surrealdb-parser")] { @@ -462,6 +515,9 @@ mod walk { /// Errors from [`parse_surrealql_ddl`]. #[derive(Debug, Clone)] +#[deprecated( + note = "SoC ruling 2026-07-22: the SurrealQL DDL parse path is deprecated — OGAR does not delegate its AST/IR concern to a foreign query-language AST API (see parse_surrealql_ddl). See docs/DISCOVERY-MAP.md D-SURREALQL-DEPRECATED." +)] pub enum ParseError { /// The input couldn't be tokenized / parsed by `surrealdb-parser`. Parse(String), diff --git a/crates/ogar-knowable-from/src/lib.rs b/crates/ogar-knowable-from/src/lib.rs index ac8e0a4..a201bf8 100644 --- a/crates/ogar-knowable-from/src/lib.rs +++ b/crates/ogar-knowable-from/src/lib.rs @@ -270,6 +270,14 @@ pub fn register_class_knowable_from( // gets wired into the call site. #[cfg(feature = "surrealql-hint")] { + // NOTE: `emit_surrealql_ddl` is `#[deprecated]` (SoC ruling 2026-07-22 + // — OGAR does not delegate its AST/IR to SurrealQL's AST API). This + // default-off `surrealql-hint` feature is downstream-deprecated with + // it; a follow-up should migrate the self-describing hint off the + // SurrealQL surface (or drop it). `#[allow(deprecated)]` keeps the + // `--features surrealql-hint` build green under `-D warnings` until + // then. See DISCOVERY-MAP D-SURREALQL-DEPRECATED. + #[allow(deprecated)] let ddl = ogar_adapter_surrealql::emit_surrealql_ddl(std::slice::from_ref(class)); store.register(class_identity, Some(ddl.as_str())) } diff --git a/docs/DISCOVERY-MAP.md b/docs/DISCOVERY-MAP.md index a289e74..4fb82d2 100644 --- a/docs/DISCOVERY-MAP.md +++ b/docs/DISCOVERY-MAP.md @@ -204,11 +204,11 @@ two halves of a cell. ADR‑026 names the cascade that ties them. | D‑VOCAB | `Class`/`Attribute`/`Association`/`EnumDecl`/`ActionDef`/`KausalSpec`/`Identity` IR | G | CODED | `ogar-vocab/` | 023 | | D‑IDENT | `class_identity(prefix,name)` = NiblePath; canonical‑form invariant | G | CODED | `ogar-ontology/` (#31) | D‑VOCAB | | D‑EMIT | `TripleEmitter` — 129 RDF predicates; SPO + TeKaMoLo | G | CODED | `ogar-emitter/` | D‑VOCAB | -| D‑SURREALQL | SurrealQL DDL adapter, parse+emit, round‑trip, identifier‑quoted | G | CODED | `ogar-adapter-surrealql/` (#32,#36) | D‑VOCAB | +| D‑SURREALQL | SurrealQL DDL adapter, parse+emit, round‑trip, identifier‑quoted | G→**DEPRECATED (2026‑07‑22)** | CODED but retired on SoC grounds: OGAR does not delegate its AST/IR concern to SurrealQL's AST (DLL) API — even if functional, an SoC error. Replacement = `render_class_with_methods` (behavior→ActionDef Rust methods) + compiled ClassView (V3). See `D‑SURREALQL‑DEPRECATED`. | `ogar-adapter-surrealql/` (#32,#36; deprecated: this PR) | D‑VOCAB | | D‑TTL | Turtle (RDF/OWL) adapter, parse+emit, round‑trip | G | CODED | `ogar-adapter-ttl/` (#37) | D‑EMIT | | D‑CHDDL | ClickHouse DDL adapter, parse+emit, dotted‑name round‑trip | G | CODED | `ogar-adapter-clickhouse-ddl/` (#38,#40) | D‑VOCAB | | D‑KNOWABLE | `KnowableFromStore` + `register_class_knowable_from`; `surrealql-hint`; **`vart-backend`** | G | CODED | `ogar-knowable-from/` (#25,#33,#43) | D‑IDENT | -| D‑HINT | `schema_ddl_hint` loop closed — self‑describing registry via emit | G | CODED | (#33) | D‑SURREALQL, D‑KNOWABLE | +| D‑HINT | `schema_ddl_hint` loop closed — self‑describing registry via emit | G→**DEPRECATED (2026‑07‑22)** | Renders DDL *into the registry as stored text* — the "code in storage" pattern the compile‑time ruling condemns; downstream‑deprecated with `D‑SURREALQL` (the `surrealql-hint` feature is default‑off). Migrate the hint to a compile‑time form or drop it. | (#33) | D‑SURREALQL, D‑KNOWABLE | | D‑ELIXIR | Elixir/HIRO SchemaSource scaffold (`gen_statem`→Rubicon) | G | CODED (scaffold) | `ogar-from-elixir/` | D‑VOCAB | | D‑HIRO‑DO | OGIT Automation → DO arm: `into_action_def` lifts `KnowledgeItem`→`ActionDef` (object_class←`relates`, kausal←`contains Trigger`, body **pointed‑to** not inlined — lossless‑DO §1); schema half of `PROBE‑OGAR‑DO‑ARM‑LIFT` green; lift→`emit_action_def`→SPO triples proven end‑to‑end (`tests/do_arm_emit.rs`, lossless‑DO holds across emit) | G | CODED (schema half) | `ogar-from-schema/src/do_arm.rs` | D‑VOCAB, D‑TTL, D‑ELIXIR, D‑EMIT | | D‑MARS‑CLASSID | MARS/Automation classids MINTED: `ConceptDomain::Automation` (0x0C), 9 concepts (`mars_application/resource/software/machine` 0x0C01‑04, `knowledge_item` 05, `mars_node_template` 06, `action_handler` 07, `action_applicability` 08, `automation_trigger` 09) — one domain spanning MARS structural CMDB + Automation DO‑arm (Auth precedent); resolves MARS‑TRANSCODING §1 deferral; passed 5+3 hardening (theorem/doctrine/integration/runtime savants + drift‑guards). Reserves the speculative rest | G | CODED | `ogar-vocab/src/lib.rs`, `ogar-class-view/src/lib.rs` | D‑VOCAB, D‑HIRO‑DO | @@ -742,6 +742,39 @@ isolation. The map's job is to keep them visible. framing in the 2026-07-04 lance-graph broadcast — the vocab's mixins axis is the answer. +- **D-SURREALQL-DEPRECATED (2026-07-22; operator ruling; regrades + `D‑SURREALQL` + `D‑HINT` G→DEPRECATED):** the ROOT reason is a + **separation-of-concerns misconception**, not a storage one (operator + correction: *"it's not about touching storage — it's the initial + misconception that runtime AST can be delegated to the SurrealQL DLL AST + API; even if it would work it would be a fundamental SoC misconception"*). + OGAR is a compiler; its IR (`Class`/`ActionDef`) is its OWN concern. The + parse arm (`parse_surrealql_ddl`, built on `surrealdb-parser`/`surrealdb-ast` + — the foreign AST DLL API) delegates OGAR's own AST/IR front-end concern to + that foreign API; the emit arm treats SurrealQL DDL as if it were part of + OGAR's IR pipeline rather than a pure adapter *output*. **Even if it worked + perfectly it would still be wrong** — an architectural error, not a + functional one. Crucially the crate was ALREADY structural-only (it never + emitted `DEFINE EVENT … WHEN … THEN`), so this is not "remove a smuggled + behavioral arm" — it retires the AST-delegation SoC pattern. **The DO arm can + never use SurrealQL**; behavior is `ActionDef`, compile-time. (Downstream + consequences that also hold, but are NOT the root: no runtime (de)serialization + of code; compile-time only; ADR-022/023 Firewall.) + Executed this PR: `#[deprecated]` on `emit_surrealql_ddl` / + `parse_surrealql_ddl` / `ParseError` + a crate-level `#![allow(deprecated)]` + (internal use only; external callers still warned) + Cargo description flag; + the one default-off caller (`ogar-knowable-from` `surrealql-hint`, itself the + "DDL into the registry as stored text" `D‑HINT` pattern) gets + `#[allow(deprecated)]` and is downstream-deprecated. **Replacement (already + shipped, all compile-time):** behavior → `render_class_with_methods` + (the entry directly below — Rust methods that ARE the ActionDef DO-arm); + spine → the compiled `ClassView` in the lance-graph⟷OGAR V3 substrate + (`lance_graph_contract::facet`). Supersedes `SURREAL-AST-AS-ADAPTER.md` §7's + 2026-06-04 "No deprecation" (see that doc's dated correction). Adapter 22 + tests still green (retained, not removed); `cargo clippy -p + ogar-adapter-surrealql` + `-p ogar-knowable-from --features surrealql-hint + -- -D warnings` clean. + - **D-OGAR-RENDER-CLASSVIEW-FIELDMASK-METHODS (transpile-chain LEG 3; 2026-07-04; [G] — CODED + tested):** the render end of the operator's chain (`ruff harvest → ogar-from-ruff lift → CompiledClass → diff --git a/docs/INTEGRATION-MAP.md b/docs/INTEGRATION-MAP.md index 69a127c..1843f8e 100644 --- a/docs/INTEGRATION-MAP.md +++ b/docs/INTEGRATION-MAP.md @@ -130,7 +130,7 @@ enter the SoA (§4). |---|---|---| | `ogar-python` | Odoo 17.0 core (`@api.depends/@api.onchange/@api.constrains` → `ActionDef` per `ADAPTERS-AND-ACTORS §3.4.1`; `_inherits` → mixins; mapping locked `ODOO-TRANSCODING.md §3,§5`) | **ABSENT** (queued) → **Track O3** | | `ruff_openproject` / `ruff_ruby_spo` | Rails AR source → SPO triples; vendored in openproject‑nexgen‑rs; test extracts `[TimeEntry, WorkPackage]` from a Rails fixture | **[G] CODED** `[per xs]` | -| `parse_surrealql_ddl` walk | SurrealQL DDL → `Vec`: DEFINE TABLE→Class; `record`→BelongsTo; `option>`→BelongsTo+optional; `option`→Attribute(required=false). NOT yet: `ASSERT IN`→EnumDecl, DEFINE EVENT→ActionDef, non-owning-side post-pass | **[H] scaffold** — feature `surrealdb-parser` wired (OGAR #23 rust 1.95), walk partial (`ogar-adapter-surrealql/src/lib.rs:143-165, 219-299`) → **Track O2** | +| `parse_surrealql_ddl` walk | SurrealQL DDL → `Vec` | **[H] scaffold →DEPRECATED (2026‑07‑22)** — SoC error: delegating OGAR's own AST/IR front‑end concern to SurrealQL's AST (DLL) API (`surrealdb-parser`/`surrealdb-ast`); OGAR sources lift via `ogar-from-`, never a foreign‑AST round‑trip. Track O2 (below) is retired, not deferred. See DISCOVERY‑MAP `D‑SURREALQL‑DEPRECATED`. | | `ogar-from-elixir` (HIRO `gen_statem` → Rubicon) | Elixir | **[G] scaffold** | | `ogar-from-ruby` (generic Rails) | — | **ABSENT**; decision: build vs reuse the nexgen ruff path → **Track O4** | @@ -138,7 +138,7 @@ enter the SoA (§4). | Adapter | Direction | Status | |---|---|---| -| `emit_surrealql_ddl(&[Class]) → String` | IR → SurrealQL DDL | **[G] CODED** (hand formatter; signature durable — body swaps to `TableDefinition::new_for_ddl().with_*() + ToSql::to_sql()` when convergence lands, `lib.rs:68-77`) | +| `emit_surrealql_ddl(&[Class]) → String` | IR → SurrealQL DDL | **[G]→DEPRECATED (2026‑07‑22)** — SoC error: OGAR's IR is its own concern; SurrealQL DDL is at most a pure adapter output, never a spine or part of OGAR's AST pipeline. Replacement: `render_class_with_methods` (behavior→ActionDef Rust methods) + compiled ClassView (V3). See DISCOVERY‑MAP `D‑SURREALQL‑DEPRECATED`. | | `ogar-adapter-ttl` (Turtle round-trip), `ogar-adapter-clickhouse-ddl` (dotted-name round-trip) | bidirectional | **[G] CODED** (#37, #38/#40) | | `ogar-knowable-from` — `KnowableFromWriter` trait + `register_class_knowable_from`; `surrealql-hint` (self-describing via emit); `vart-backend` (`Tree`, NULL-terminated keys) | IR → registry | **[G] CODED** (#25/#33/#43); Lance writer impl = `lance-bind` boundary **[H]** | | `TripleEmitter` (129 RDF predicates, SPO + TeKaMoLo) | IR → triples | **[G] CODED** | @@ -322,7 +322,12 @@ IDENTITY A NodeGuid ✅(#480) ──→ B SchemaSig→ClassView live ─┐ OGAR O1 Class traversal API (leaf, ~50 LOC) ──→ O2's non-owning post-pass (G-pass: the real dependent — producers BUILD, consumers NAVIGATE; O3/O4 benefit from O1 but are not gated by it) - O2 parse walk completion (EnumDecl lift · DEFINE EVENT→ActionDef · non-owning post-pass) + O2 parse walk completion — ⊘ RETIRED (2026-07-22): the SurrealQL DDL + parse path is deprecated on SoC grounds (OGAR does not delegate + its AST/IR to SurrealQL's foreign AST API); its + "DEFINE EVENT→ActionDef" item was additionally the forbidden + behavior-in-DDL trap. Behavior = ActionDef, compile-time. See + DISCOVERY-MAP D-SURREALQL-DEPRECATED. O3 ogar-python (Odoo) · O4 ruby producer decision (build vs reuse nexgen ruff) O5 content_tier + ContentResolver (needs T-backends: all exist) O6 ADR-026 draft (ready bucket; enriched by Q1's verdict) diff --git a/docs/SURREAL-AST-AS-ADAPTER.md b/docs/SURREAL-AST-AS-ADAPTER.md index 7f6f291..6a6d92b 100644 --- a/docs/SURREAL-AST-AS-ADAPTER.md +++ b/docs/SURREAL-AST-AS-ADAPTER.md @@ -395,6 +395,28 @@ scaffold dissolves once graduation completes. ## 7. What changes in the existing crates +> **⊘ SUPERSEDED IN PART (operator ruling, 2026-07-22 — a separation-of-concerns +> error).** The "**No deprecation**" of `ogar-adapter-surrealql` below +> (bullet 1, CARVED v0 2026-06-04) is **reversed**: the whole SurrealQL DDL +> adapter (both `emit_surrealql_ddl` and `parse_surrealql_ddl`) is now +> `#[deprecated]`. The reasoning is orthogonal to this doc's carving and does +> not weaken it: this doc correctly kept the **behavioral arm** out of DDL +> (`DEFINE EVENT` is the rejected hijack, §0), and the adapter never carried +> behavior. The *new* ground is a **separation-of-concerns** one, NOT a storage +> one (operator: *"it's not about touching storage — it's the initial +> misconception that runtime AST can be delegated to the SurrealQL DLL AST API; +> even if it would work it would be a fundamental SoC misconception"*). OGAR is +> a compiler; its AST/IR is its OWN concern: `parse_surrealql_ddl` delegates +> that front-end concern to `surrealdb-parser`/`surrealdb-ast` (the foreign AST +> DLL API), and `emit` treats DDL as if it were part of OGAR's IR pipeline +> rather than a pure adapter *output*. The DO arm is `ActionDef`, compile-time +> only; the replacement is `ogar-render-askama::render_class_with_methods` +> (Rust methods = the ActionDef DO-arm) + the compiled `ClassView` (V3), both +> compile-time. `ogar-vocab`'s `Class`/`ActionDef`/`ActionInvocation` (bullet 2) +> are UNAFFECTED — they stay canonical; only the DDL-string adapter is retired. +> See `docs/DISCOVERY-MAP.md` `D-SURREALQL-DEPRECATED`. (Append-only: the +> original §7 text is retained below, read through this note.) + Nothing immediate — this doc *records* the decision; the trajectory was already correct. The pieces this doc explicitly endorses: