Capabilities and frames

Faber और ऑपरेटिंग सिस्टम द्वारा I/O लागू करने के हर तरीके के बीच का जोड़।

ad Faber का निम्न-स्तरीय capability call primitive है — Faber कोड और बाहरी दुनिया के बीच की सीमा। यह route string से पहचाने गए host resource के साथ एक typed conversation (sermo) खोलता है, फिर directional half-streams के ज़रिए structured frames (scrinium) का आदान-प्रदान करता है। Host kernel हर route को एक pluggable provider crate तक भेजता है, जो वास्तविक I/O लागू करता है — filesystem, networking, console, time, randomness, या OS द्वारा किए जा सकने वाले किसी भी अन्य कार्य को।

`ad` primitive#

ad एक keyword है, function नहीं। यह एक ascii literal द्वारा नामित route के साथ opaque conversation खोलता है और opener data वैकल्पिक होता है:

# Simple materialized call: open, send opener, drain response
fixum textus content ← ad 'solum:lege' ("config.toml") ↦ textus

# Typed conversation handle for streaming interaction
fixum sermo s ← ad 'processus:curre' ("ls", ["-la"])

Route string prefix:verb pattern का पालन करती है। Host kernel केवल prefix पर match करता है — उस prefix के अंतर्गत आने वाले सभी verbs का स्वामित्व provider के पास होता है:

solum:lege   ─┐
solum:modum  ─┼─►  prefix "solum"  ──►  solum provider crate
solum:vincula─┘

ad foreign function interface नहीं है। यह C functions को call नहीं करता, dynamic libraries load नहीं करता और inline assembly embed नहीं करता। यह structured message passing boundary है: Faber typed frames भेजता और typed frames प्राप्त करता है, बिना यह जाने कि provider Rust में implement किया गया है, in-process चलता है, system call को delegate करता है या remote host को forward करता है।

फ़्रेम प्रकार#

Compiler द्वारा स्वामित्व वाले पाँच types frame system बनाते हैं:

Type	भूमिका	मुख्य surface
`sermo`	Conversation handle — चल रहा bidirectional exchange	`ad` द्वारा बनाया जाता है; `↦ T` के ज़रिए drain किया जाता है या views में split किया जाता है
`scrinium<T>`	Frame envelope — conversation में एक structured message	Fields: `id`, `call`, `status`, `data`, `created_ms`, `from`, `trace`
`status`	Lifecycle marker enum	`request`, `item`, `byte`, `bulk`, `done`, `error`, `cancel`
`meus<T>`	Outbound half-stream — provider को frames भेजता है	`da(T)`, `fini() → status`
`tuus<T>`	Inbound half-stream — provider से frames प्राप्त करता है	`accipe()`, `cursor()`, `exhauri()`, `fini()`

Directional views का उपयोग#

# Open a conversation, get directional views
fixum sermo s ← ad 'solum:scribe' ("output.txt")
fixum meus<textus> out ← s.meus<textus>()
fixum tuus<textus> input ← s.tuus<textus>()

# Send content frames
out.da("line one")
out.da("line two")
out.fini()

# Read response frames
itera ex input.cursor() fixum frame {
    nota frame.data
}
fixum status inbound ← input.fini()

सरल materialization#

सामान्य स्थिति में — open करना, opener भेजना और सभी response frames को एक value में drain करना — sermo ↦ T conversation को समेट देता है:

# Read a file: open + drain into textus
fixum textus body ← ad 'solum:lege' ("config.toml") ↦ textus

# Parse JSON from an HTTP response
fixum json data ← ad 'http:peti' ("https://api.example.com/data") ↦ json

Materialization एक type-directed collector का उपयोग करता है: ↦ textus सभी inbound frames को concatenate करता है, ↦ json concatenated payload को parse करता है और ↦ lista<T> frames को एक list में collect करता है।

होस्ट प्रदाता#

Effect families को faberlang/host-providers-rs के अंतर्गत अलग-अलग provider crates के रूप में implement किया जाता है। प्रत्येक provider अपने prefix के अंतर्गत आने वाले सभी verbs का स्वामी होता है:

Provider	Prefix	I/O domain
`solum`	`solum:*`	Filesystem: read, write, metadata, directory operations
`processus`	`processus:*`	Process execution: spawn, pipe, exit codes
`consolum`	`consolum:*`	Console I/O: stdin, stdout, stderr
`tempus`	`tempus:*`	Time: now, sleep, timers
`aleator`	`aleator:*`	Randomness: entropy, distributions
`http`	`http:*`	HTTP client (Tier D, जब उपलब्ध होगा)

Providers अलग-अलग crates हैं और उनकी dependencies भी अलग हैं — solum HTTP को pull in नहीं करता और http filesystem code को pull in नहीं करता। प्रत्येक provider एक register() function export करता है, जिसे generated host manifest startup पर call करता है।

परत स्टैक#

Faber source:     ad 'solum:lege' (path) ↦ textus
Compiler:         sermo open + generic attach (no provider crate names)
Runtime:          HostDispatch + conversation protocol (faber-runtime)
Kernel:           route(frame) → provider for prefix
Provider:         solum provider reads file, returns content

Compiler generic dispatch emit करता है — generated code में provider crate names कभी embed नहीं करता। Runtime HostDispatch और conversation protocol उपलब्ध कराता है। Kernel (host-kernel-rs से) prefix के आधार पर frames को सही provider तक route करता है। Provider (host-providers-rs से) वास्तविक I/O करता है।

इसका अर्थ है कि generated Faber code provider-neutral है। Compile manifest बदलकर उसी compiled binary को अलग-अलग provider implementations के साथ link किया जा सकता है — production के लिए real filesystem provider और testing के लिए mock provider।

कंपाइल मैनिफ़ेस्ट#

कौन-से providers link किए जाएँगे, यह generated compile manifest और faber.toml की [dispatch] table नियंत्रित करते हैं:

[target.rust]
host = "native"

[dispatch]
providers = ["solum", "processus", "consolum", "tempus", "aleator"]

[dispatch.providers.http]
enabled = true

Authoring के दौरान missing providers runtime E_NO_ROUTE error उत्पन्न करते हैं। Strict mode में (भविष्य में), program में मौजूद हर ad prefix को compile manifest में दिखाई देना होगा और compiler यह validate करेगा कि provider का capability manifest उपयोग किए गए routes को cover करता है।

आर्किटेक्चर#

Host platform को faberlang organisation के तीन repositories में बाँटा गया है:

Repository	भूमिका
`host-kernel-rs`	Thin router — `Frame`, `Conversation`, terminal lifecycle, prefix dispatch, structured errors (`E_NO_ROUTE`) और capability manifest aggregation का स्वामी
`host-native-rs`	Native attach — workers, `register_providers` startup hook और generated `host_register.rs` integration
`host-providers-rs`	Provider implementations — per-family crates (`solum`, `processus`, आदि) वाला Cargo workspace

प्रत्येक provider crate अपनी native dependencies का स्वामी है। HTTP enabled होने पर http provider केवल तभी hyper और tokio pull in करता है। solum provider standard file APIs का उपयोग करता है और उसे किसी अतिरिक्त network dependencies की आवश्यकता नहीं होती।

एक ही route, कोई भी host। क्योंकि ad route strings पर dispatch करता है और providers pluggable हैं, इसलिए वही Faber source native binary (host-native-rs), WASM runtime (Frame/Wasm adapter के रूप में host-kernel) या TypeScript Node.js process (host-providers-ts) को target कर सकता है, बिना Faber code की एक भी line बदले।

Norma wrappers#

अधिकांश Faber code सीधे ad call नहीं करता। Norma standard library सामान्य ad routes को typed functions में wrap करती है:

# Norma wraps ad in typed, reviewed functions
functio lege(textus via) → textus {
    redde ad 'solum:lege' (via) ↦ textus
}

functio scribe(textus via, textus content) → vacuum {
    fixum vacuum _ ← ad 'solum:scribe' (via, content) ↦ vacuum
}

functio curre(textus command, lista<textus> args) → textus {
    redde ad 'processus:curre' (command, args) ↦ textus
}

ये wrapper functions ad boundary के पार होने वाले I/O के तथ्य को छिपाए बिना type safety, documentation और error handling प्रदान करते हैं। Norma wrappers open source हैं और norma/src/ के अंतर्गत रहते हैं।

संदर्भ#

radix/docs/design/frame-stream-types.md — sermo, scrinium, status, meus, tuus की पूरी specification
radix/docs/design/host-provider-gateway.md — thin router architecture, provider contracts और compile manifest
faberlang/host-kernel-rs/ — kernel router implementation
faberlang/host-native-rs/ — native attach और registration
faberlang/host-providers-rs/ — provider crates (solum, processus, consolum, tempus, aleator, http)
examples/corpus/ad/ — sermo exempla files