VUSL: A Provider Neutral Semantic View for Rangoon
VUSL is a reviewable semantic interoperability design. Its current Rangoon subset is an experimental offline Rust inspection library that preserves native provenance, refuses unsafe inference, and does not claim a deployed network protocol or universal compatibility.
Public draft v0.1 / Under development. Planned Rangoon integration.
What VUSL is for
VUSL gives different systems a shared vocabulary for capabilities, operations, artifacts, observations, and relationships. The vocabulary is provider neutral, but it does not erase provider meaning. A translated fact keeps its native identity, version, provenance, and stated loss so a reader can tell what was reported and what was inferred.
This is a semantic view over existing records, not a second content database, executable workflow language, policy language, identity provider, or authority engine. A VUSL document can describe a report; it cannot turn that report into permission or proof of effect.
Rangoon owns authoring and inspection
Rangoon owns capability authoring, source lineage, decomposition, composition, revisions, instruction compilation, export, and inspection. Those local workflows are designed to work without LNSAT, OpenShell, or another provider. Each external system keeps its own identity, authorization, enforcement, and operational responsibilities.
The planned Rangoon integration is therefore an ownership boundary: Rangoon may author and inspect a semantic view, while a provider remains responsible for its native contract. The integration is planned work for Rangoon and is not connected to Hypler production.
The current Rust subset is offline and small
The first implemented subset is an experimental Rust JSON inspection library. It reads supplied, bounded bytes and applies the closed D0a observation rules. It can canonicalize accepted documents, calculate a local identity digest, and return fixed diagnostics. It does not open a transport, discover credentials, call an engine, or mount a connected UI.
The broader VUSL architecture describes future semantic families and adapter boundaries. Those future families are design targets, not a claim that Rangoon currently serializes every family. The current subset is intentionally narrower than the architecture.
Exact wire identifiers and closed shape
The current tokens are exact: `rangoon.rusl.v0.1` is the language identifier and `rangoon.rusl.observe.v0.1` is the D0a profile identifier. VUSL does not add a `vusl` wire alias. A future alias would require a separately versioned migration and is unsupported by the current parser.
Every D0a document has nine required top level keys: `languageVersion`, `kind`, `id`, `createdAt`, `origin`, `native`, `semantic`, `extensions`, and `translation`. The object shape is closed. Unknown core keys, duplicate names, unsupported versions, and invalid semantic variants are refusals rather than invitations to guess.
Bounds make refusal predictable
A candidate D0a document is capped at 131,072 UTF 8 bytes. The parser allows maximum JSON depth 16, 256 total JSON values, 32 fields in one object, and 64 entries in one array. Descriptive strings are capped at 4,096 UTF 8 bytes and opaque tokens at 128 ASCII bytes. These are bounds for one minimized semantic document, not limits on a provider's source file or native media.
The parser refuses an oversized document without truncating, splitting, retrying, or returning partial success. Fixed errors include `input_limit`, `depth_limit`, `value_limit`, `collection_limit`, `duplicate_field`, and `invalid_json`. A bound is useful only when failure is explicit and reviewable.
Native bytes stay omitted
The current profile deliberately omits native bytes. `native.state` remains `omitted`, and a document cannot claim a host reference, lossless round trip, or native digest. This keeps a pure parser from becoming an unreviewed storage or retrieval path.
No D0a document grants authority. Provider policy, engine authorization, runtime completion, and independently checked effect remain separate facts. A reported `allow` can be displayed as a report with `authority: none`; it cannot authorize an action. Any future UI must escape source text for display. Fixed parser diagnostics do not echo provider payloads, URLs, secrets, or input excerpts.
Compatibility is per operation and direction
VUSL compatibility is qualified per operation and direction. An adapter must identify the provider product and version, native protocol and version, adapter revision, exact operation subset, and applicable profile. A connector may inspect a policy report while being unable to apply policy or authorize an action.
External references use exact system, environment, engine, native contract, and native object identities. Matching names, timestamps, trace strings, or digests do not create a cross provider join. If a critical constraint cannot be preserved or understood, the operation refuses.
MCP, A2A, and OpenTelemetry remain complementary
VUSL does not replace MCP, A2A, OpenTelemetry, Trace Context, or other native standards. MCP defines tool, resource, and prompt interfaces; A2A describes agent tasks and messages; OpenTelemetry provides telemetry collection and export conventions. VUSL can preserve a relationship to one of these contracts when a named adapter proves the relationship and its loss.
Choosing a common VUSL profile does not establish compatible MCP or A2A versions, authenticated ingress, telemetry completeness, or execution permission. Native negotiation and qualification remain independent.
Examples explain shape, not installed capability
The repository's examples are conceptual or synthetic unless a source packet says otherwise. They show how a capability descriptor or observation may carry a profile, semantic family, native reference, and translation loss. They do not prove a connected provider, an installed connector, an executable permission, or a certified interchange result.
The same rule applies to source and build conformance. A pinned README, parser fixture, or local validation run can establish what that artifact says and does. It cannot establish a universal SDK, live protocol, or another provider's behavior.
Roadmap is proof driven
Future work needs an immutable profile and schema identity, independent cross language parser evidence, qualified host mapping, boundary tests, and explicit privacy and credential controls. A future host reference would need separately reviewed encrypted custody. A future transport would need authentication, tenant isolation, framing, message limits, cancellation, ordering, recovery, and redaction rules.
Until those gates are met, VUSL remains a public reviewable design with an experimental offline subset. Rangoon can build toward the planned integration while preserving native contracts and refusing unsupported claims.
AI systems, frameworks and native-contract coverage
Current source coverage and integration direction. No connected provider or framework adapter is qualified by this public draft.
Rangoon — Planned integration. Capability authoring, composition, revisions, export and inspection remain with Rangoon.
OpenShell — Offline source work. Synthetic typed-window mapping and an unmounted read-only client/host path; no qualified live gateway or VUSL network binding.
LNSAT — Offline evidence inspection. Native-shaped JSON decoder preserves authorization, attempts, receipts and reconciliation as distinct facts. No connected engine claim.
LangGraph / LangSmith — Reference ecosystem / unassessed adapter. Named in the pinned Rangoon capability audit. No VUSL adapter or framework compatibility is qualified.
MCP / Agent Skills / MCP Apps — Native contract references. Tools, resources, prompts, skill packages and embedded application contracts keep their own versions and host requirements.
A2A / ACP / AG-UI — Native contract references. Agent tasks, editor sessions and UI events remain separate native lifecycles; listing them does not establish adapter support.
OpenAPI / AsyncAPI / CloudEvents — Native contract references. API descriptions, asynchronous interfaces and delivery metadata are not execution authority.
OpenTelemetry / Trace Context / OCSF — Native contract references. Telemetry, correlation and security-event representations do not prove authorization or an external effect.
OAuth / OIDC / SPIFFE — Identity references. Native identity and credential semantics remain independent. VUSL does not issue credentials or grants.
W3C PROV / SLSA — Provenance references. Provenance and build-evidence concepts require their own scoped evidence; a document digest is not an authenticated producer.
A plain-language walkthrough (hypothetical)
Imagine a reviewer receives a small provider report about one operation. A future Rangoon integration could retain the provider name, version, native object identity, report status, and any translation loss, then present a bounded VUSL observation for inspection. The semantic view would make the source and uncertainty easier to read; it would not rewrite the provider record or create a new permission.
In this hypothetical flow, the offline D0a inspector receives already supplied bytes, checks the closed document shape and limits, canonicalizes an accepted document, and computes its local document identity. A refusal stays a refusal. No network lookup, credential discovery, engine call, or connected interface follows from parsing those bytes.
The reviewer then reads separate facts: what the provider reported, whether a native system authorized an action, whether an attempt occurred, and whether an effect was independently checked. A report that says allow can remain an observation with no authority. This walkthrough explains the intended boundary; it is not evidence of a connected Rangoon demonstration or a live provider result.
Rust implementation and Python reference checks
The pinned conformance guide identifies the D1 Rust implementation as `inspect(&[u8]) -> Result<Inspection, Diagnostic>`. On success, the inspection exposes the document kind, canonical bytes, and a SHA-256 document identity. The caller supplies bytes and owns file selection, transport, and storage; the library has no authority to authorize or execute.
The same guide identifies an independent Python reference in `crates/rangoon-language/tests/reference_d0a.py`. It validates and serializes the same bounded subset, acts as a test oracle, and is not a supported Python SDK. Rust and Python replay shared fixtures, so agreement supplies useful fixture evidence without proving exhaustive equivalence, formal correctness, or certification.
This language split has a clear purpose: Rust is the described inspection implementation, while Python provides an independent reference for fixture and boundary checks. Neither language choice creates provider compatibility, a public SDK, or a network binding. Those claims require separately qualified artifacts and operation-specific evidence.
Reproducible source reading and what checks prove
A reproducible review starts by pinning the VUSL commit, the selected files, and the conformance vectors. The repository's `python3 scripts/validate.py` check verifies its extracted artifact inventory, vector hashes, and local document links. The README describes the six executable canonical vectors as exact input, canonical JSON, SHA-256, and domain-separated identity expectations; negative vectors pin refusal cases.
The Rust parser lives in Rangoon, not in the extracted VUSL specification repository. The pinned conformance guide points to Rangoon commit `d23b2b73e7d0436325a03264144ac87c0056c10b`. In that checkout, with the declared Rust toolchain and cached locked dependencies, the documented D1 checks are `cargo test --locked --offline -p rangoon-language` and `python3 crates/rangoon-language/tests/reference_d0a.py`. These are reproduction instructions from the source guide, not checks executed by this website or evidence of a released package.
The specification-repository validator establishes document and artifact integrity; it does not execute the Rangoon parser. The separate Rust and Python commands replay implementation fixtures. Neither result proves general JSON Canonicalization Scheme equivalence, provider compatibility, an authenticated producer, or a live engine effect. A missing offline dependency is a failed or unrun check, not evidence of conformance. A passing vector replay also cannot turn a draft into a stable protocol or universal SDK.
The source record therefore keeps three claims separate: what the pinned specification says, what a local implementation proves for named vectors, and what a provider or deployment proves at runtime. Any future build packet should report the exact command, toolchain, fixture set, and limitations beside its result.
Security reasoning and terms to keep distinct
VUSL security depends on refusing authority promotion. Native authentication, authorization, enforcement, execution, and effect verification stay with the relevant native system. Mappings expose loss and uncertainty, refuse critical constraints that cannot be preserved, and do not silently join independently sourced evidence. The current D0a profile omits native bytes and cannot claim lossless translation.
The pinned security policy and README set implementation boundaries: do not resolve source references as URLs or filesystem paths, execute imported descriptions, discover credentials implicitly, or use a VUSL document as a grant. Bound parsers and queues, escape provider text before display, and keep secrets out of serialized observations and fixed diagnostics. These are design rules for the profile, not evidence that a future connected adapter has passed a security review.
Useful glossary distinctions follow: a document identity is a digest of canonical bytes, not a signature or approval; `observation_only` describes inspection without outbound consequence control; `unassessed` means evidence is insufficient for a support claim; and `lossless_translation` needs pinned native identity, retained source evidence, and round-trip proof. A shared name, timestamp, trace, or digest cannot establish a cross-provider join by itself.