Deprecate ogar-adapter-surrealql — a separation-of-concerns error; point to V3 replacement

[AdaWorldAPI]

What (root reason corrected)

Operator ruling (2026-07-22). The root reason is a separation-of-concerns error, NOT a storage/serialization 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:

• 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. OGAR sources lift into Class via OGAR's own ogar-from-<lang> front-ends, never a foreign-AST round-trip.
• emit_surrealql_ddl treats SurrealQL DDL as if it were part of OGAR's IR pipeline; DDL is at most a pure adapter output, never a spine.

Even if it worked perfectly it would still be wrong — an architectural (SoC) error, not a functional one. The crate was ALREADY structural-only (never emitted DEFINE EVENT … WHEN … THEN), so this is not "remove a smuggled behavioral arm" — it retires the AST-delegation 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; compile-time only; ADR-022/023 Firewall.)

Replacement (already shipped, compile-time)

• Behavior -> ogar-render-askama::render_class_with_methods (Rust methods that ARE the ActionDef DO-arm; on_enter => &mut self).
• Spine -> the compiled ClassView in the lance-graph<->OGAR V3 substrate.

Code (additive, no deletion — 22 adapter tests stay green)

• #[deprecated] on emit_surrealql_ddl, parse_surrealql_ddl, ParseError, each noting the SoC reason + replacement + DISCOVERY-MAP D-SURREALQL-DEPRECATED.
• Crate-level #![allow(deprecated)] — silences only THIS crate's internal use; external callers still get the warning.
• ogar-knowable-from (the ONLY external caller — default-off surrealql-hint): #[allow(deprecated)] + downstream-deprecated comment.
• Cargo description flagged DEPRECATED.

Canon (append-only; regrade in place)

• DISCOVERY-MAP: D-SURREALQL + D-HINT regraded G->DEPRECATED; new dated D-SURREALQL-DEPRECATED entry recording the SoC ruling + replacement map.
• SURREAL-AST-AS-ADAPTER §7: dated correction superseding the 2026-06-04 "No deprecation" line (orthogonal to that doc's behavior-out-of-DDL carving; the new ground is the AST-delegation SoC error). ogar-vocab Class/ActionDef/ActionInvocation unaffected.
• INTEGRATION-MAP: emit/parse rows regraded DEPRECATED; Track O2's "DEFINE EVENT->ActionDef" retired.

Verified

• cargo clippy -p ogar-adapter-surrealql --all-targets -- -D warnings -> exit 0
• cargo clippy -p ogar-knowable-from --features surrealql-hint --all-targets -- -D warnings -> exit 0
• adapter tests 22/22; fmt clean.

Scope note

Sibling storage-membrane adapters (ogar-adapter-ttl, -postgres-ddl, -clickhouse-ddl) are out of scope — they are pure adapter outputs (storage egress), not an AST-delegation into OGAR's IR pipeline. -postgres-ddl is operator-ruled as the transactional System-of-Record.

🤖 Generated with Claude Code

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_adf596da-e6a5-4997-af75-a4b7c3b3ee72)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3ffe5f928a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep the integration map's SurrealQL status consistent

This row now says the SurrealQL parse path is deprecated and O2 is retired, but the same living map still advertises parse_surrealql_ddl walk [H scaffold] in the overview and S3 as [H] partial walk, while S2 still lists emit_surrealql_ddl as [G] wired. Because this document explicitly says implementation follows the map, readers using the overview or seam table will continue planning against the retired SurrealQL paths; please update those remaining entries as part of this deprecation.

Useful? React with 👍 / 👎.