feat(typia): add LLMData derive and native lenient parser (#335)

## Summary
- add a serde-based `LLMData` runtime trait to `typia` with `parse`,
`validate`, and `stringify`
- add internal native lenient JSON parsing (markdown code block
extraction, junk-prefix skipping, comments, unquoted keys, trailing
commas, partial keyword recovery, unclosed recovery, unicode surrogate
decoding, depth guard)
- replace `typia-macros` scaffold with real `#[derive(LLMData)]`
supporting structs/enums and rejecting unions
- add runtime + compile-fail tests for parser behavior, serde path
failures, and derive constraints
- update typia contracts/docs and align AGENTS wording for typia
stability contracts

## Validation
- `cargo fmt --all`
- `TRYBUILD=overwrite cargo test -p typia derive_llm_data_rejects_union
-- --exact`
- `cargo test`

Author: kdy1

AGENTS.md

@@ -55,10 +55,10 @@
 - `docs/project-thenv.md`: Thenv multi-component project index.
 - `docs/project-public-docs.md`: Public docs app project index.
 - `docs/project-serde-feather.md`: Serde Feather multi-crate project index.
-- `docs/project-typia.md`: Typia scaffold-stage multi-crate project index.
+- `docs/project-typia.md`: Typia multi-crate project index.
 - `docs/project-dexdex.md`: DexDex multi-runtime project index.
-- `docs/crates-typia-core-foundation.md`: Typia core runtime scaffold contract.
-- `docs/crates-typia-macros-foundation.md`: Typia macros scaffold contract.
+- `docs/crates-typia-core-foundation.md`: Typia core runtime LLM data contract.
+- `docs/crates-typia-macros-foundation.md`: Typia macros derive contract.
 - `docs/apps-dexdex-desktop-app-foundation.md`: DexDex app runtime and integration foundation contract.
 - `docs/apps-dexdex-ui-contract.md`: DexDex UI and interaction contract.
 - `docs/apps-dexdex-user-guide-contract.md`: DexDex end-user workflow contract.

Cargo.lock

@@ -11,8 +11,8 @@
 - `crates/nodeup`: Rust-based Node.js version manager.
 - `crates/serde-feather`: Size-first serde runtime-facing core crate.
 - `crates/serde-feather-macros`: Proc-macro companion crate for serde-feather.
-- `crates/typia`: Type-safe JSON schema validation core scaffold crate.
-- `crates/typia-macros`: Proc-macro companion scaffold crate for typia.
+- `crates/typia`: Serde-based LLM JSON runtime crate.
+- `crates/typia-macros`: Proc-macro derive companion crate for typia.
 
 ### Rust Workspace Rules
 
@@ -46,7 +46,8 @@
 ### typia-Specific Rules
 
 - Keep `typia` as the runtime-facing crate and `typia-macros` as the proc-macro companion crate.
-- Keep scaffold-stage API policy explicit: do not treat v0 public identifiers as stable until documented in `docs/project-typia.md` and `docs/crates-typia-core-foundation.md`.
+- Keep stable typia identifiers (`LLMData`, `LlmJsonParseResult`, `LlmJsonParseError`, and `#[derive(LLMData)]`) synchronized with `docs/project-typia.md`, `docs/crates-typia-core-foundation.md`, and `docs/crates-typia-macros-foundation.md`.
+- Keep non-contracted v0 identifiers explicitly documented as unstable until promoted in typia contract docs.
 - Keep future macro/runtime compatibility constraints synchronized with typia project and crate contracts.
 
 ### Multi-Component Contract Sync

crates/AGENTS.md

@@ -3,10 +3,14 @@ name = "typia-macros"
 version = "0.1.0"
 edition = "2024"
 license = "MIT"
-description = "Proc-macro scaffold crate for typia"
+description = "Proc-macro derive crate for typia"
 publish = false
 
 [lib]
 proc-macro = true
 
 [dependencies]
+proc-macro-crate = "3.3.0"
+proc-macro2 = "1.0.94"
+quote = "1.0.39"
+syn = { version = "2.0.100", features = ["full"] }

crates/typia-macros/Cargo.toml

@@ -1,18 +1,50 @@
 #![forbid(unsafe_code)]
 
-//! Proc-macro scaffold crate for `typia`.
-//!
-//! Public derive identifiers are intentionally not stabilized yet.
+//! Proc-macro derive implementation for `typia`.
 
 use proc_macro::TokenStream;
+use proc_macro_crate::{FoundCrate, crate_name};
+use proc_macro2::{Span, TokenStream as TokenStream2};
+use quote::quote;
+use syn::{Data, DeriveInput, Ident, parse_macro_input};
 
-/// Internal-only scaffold macro used to keep the proc-macro crate wired into
-/// the workspace.
-///
-/// This identifier is intentionally not part of the stable public contract and
-/// may change.
-#[doc(hidden)]
-#[proc_macro]
-pub fn __typia_scaffold(input: TokenStream) -> TokenStream {
-    input
+#[proc_macro_derive(LLMData)]
+pub fn derive_llm_data(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    match expand_llm_data(&input) {
+        Ok(tokens) => tokens.into(),
+        Err(error) => error.into_compile_error().into(),
+    }
+}
+
+fn expand_llm_data(input: &DeriveInput) -> syn::Result<TokenStream2> {
+    match input.data {
+        Data::Struct(_) | Data::Enum(_) => {}
+        Data::Union(_) => {
+            return Err(syn::Error::new_spanned(
+                input,
+                "`LLMData` can only be derived for structs and enums",
+            ));
+        }
+    }
+
+    let typia_path = typia_path();
+    let ident = &input.ident;
+    let generics = &input.generics;
+    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+    Ok(quote! {
+        impl #impl_generics #typia_path::LLMData for #ident #ty_generics #where_clause {}
+    })
+}
+
+fn typia_path() -> TokenStream2 {
+    match crate_name("typia") {
+        Ok(FoundCrate::Itself) => quote!(crate),
+        Ok(FoundCrate::Name(name)) => {
+            let ident = Ident::new(&name.replace('-', "_"), Span::call_site());
+            quote!(::#ident)
+        }
+        Err(_) => quote!(::typia),
+    }
 }

crates/typia-macros/src/lib.rs

@@ -4,5 +4,17 @@ version = "0.1.0"
 edition = "2024"
 license = "MIT"
 description = "Type-safe JSON schema validation for Rust"
+publish = false
+
+[features]
+default = ["derive"]
+derive = ["dep:typia-macros"]
 
 [dependencies]
+serde = { version = "1.0.219", features = ["derive"] }
+serde_json = "1.0.145"
+serde_path_to_error = "0.1.17"
+typia-macros = { version = "0.1.0", path = "../typia-macros", optional = true }
+
+[dev-dependencies]
+trybuild = "1.0.114"

crates/typia/Cargo.toml

@@ -1,25 +1,52 @@
 # typia
 
-`typia` is a scaffold-stage Rust project for type-safe JSON schema validation.
+`typia` provides serde-based LLM JSON utilities for Rust.
 
-## Goal and Current Status
+## Stable APIs
 
-- Goal: provide a stable runtime foundation for type-safe validation and schema workflows.
-- Current status: scaffold only; the crate does not expose stabilized public APIs yet.
-- API policy: v0 public function/type and macro identifiers are intentionally not frozen at this stage.
+- `LLMData` trait
+  - `parse(input: &str) -> LlmJsonParseResult<Self>`
+  - `validate(value: serde_json::Value) -> Result<Self, serde_json::Error>`
+  - `stringify(&self) -> Result<String, serde_json::Error>`
+- `LlmJsonParseResult<T>`
+- `LlmJsonParseError`
+- `#[derive(LLMData)]` (from `typia-macros`, re-exported by `typia`)
 
-## Component Architecture
+## Example
 
-- `core`: `crates/typia` (active scaffold)
-- `macros`: `crates/typia-macros` (active scaffold)
+```rust
+use typia::{
+    LLMData,
+    serde::{Deserialize, Serialize},
+};
 
-Future macro-generated code must remain compatible with the core runtime contracts.
+#[derive(Debug, Serialize, Deserialize, LLMData)]
+struct User {
+    id: u32,
+    name: String,
+}
 
-## Current Non-Goals
+fn main() {
+    let parsed = User::parse("{id: 1, name: \"alice\",}");
+    println!("{parsed:?}");
+}
+```
+
+## Lenient Parser Behaviors
+
+`LLMData::parse()` uses typia's internal lenient JSON parser before serde validation.
+
+Supported recovery behaviors:
 
-- Freezing public runtime API identifiers before scaffold-stage contracts are finalized.
-- Defining stable derive macro names or expansion schemas before macro interface contracts are stabilized.
-- Providing production-ready validation semantics before core and macro contracts are documented as active.
+- markdown ` ```json ... ``` ` extraction
+- junk prefix skipping before JSON payloads
+- JavaScript comments (`//`, `/* ... */`)
+- unquoted object keys
+- trailing commas
+- partial keywords (`tru`, `fal`, `nul`)
+- unclosed strings/brackets with partial recovery
+- unicode escapes (including surrogate-pair decoding)
+- depth guard (`MAX_DEPTH = 512`)
 
 ## Local Validation