@syntropika/tembra-engine-wasm 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,9 +7,15 @@ Orbs own their behavior and validation. Tembra manages how they work together th
7
7
  lifetime through a shared Rust engine. Applications can combine Rust and TypeScript across
8
8
  servers, browsers, Web Workers and React Native.
9
9
 
10
+ An orb is either trusted application code (Rust, or TypeScript in the host runtime) or a built
11
+ `.wasm` artifact that runs isolated in WebAssembly. Both kinds install into the same host and use
12
+ the same lifecycle.
13
+
10
14
  ## What it provides
11
15
 
12
16
  - **Composable orbs.** Declare the services an orb provides and the dependencies it consumes.
17
+ - **Isolated orbs.** Build TypeScript or a compiled component against a WIT contract, then grant
18
+ filesystem and network access per orb at installation.
13
19
  - **Consistent state.** Validate changes before publishing them and observe the values that matter.
14
20
  - **Controlled updates.** Replace implementations and migrate state while respecting active work.
15
21
  - **Shared resources.** Tie resources and tasks to the host, orb or object that owns them.
@@ -17,26 +23,46 @@ servers, browsers, Web Workers and React Native.
17
23
 
18
24
  ## Repository
19
25
 
20
- | Directory | Contents |
21
- | ------------------------------------------------------ | ----------------------------------------------------------------- |
22
- | [crates/core/](crates/core/) | Shared Rust engine for ownership, state revisions and orb updates |
23
- | [crates/tembra/](crates/tembra/) | Rust interface for declaring and running orbs |
24
- | [crates/bridge/](crates/bridge/) | Communication between the engine and its platform integrations |
25
- | [crates/executor-js/](crates/executor-js/) | Embedded JavaScript execution through V8 for Rust applications |
26
- | [crates/node-binding/](crates/node-binding/) | Connects Node.js to the Rust engine |
27
- | [crates/mobile/](crates/mobile/) | Shared Rust kernel bindings for Swift and Kotlin |
28
- | [crates/browser-wasm/](crates/browser-wasm/) | Makes the Rust engine available in browsers and Workers |
29
- | [packages/ts/sdk/](packages/ts/sdk/) | TypeScript SDK and orb tooling |
30
- | [packages/ts/engine-node/](packages/ts/engine-node/) | Native engine packaging and builds |
31
- | [packages/ts/engine-wasm/](packages/ts/engine-wasm/) | WASM engine packaging and builds |
32
- | [packages/swift/](packages/swift/) | Swift bindings for iOS and macOS |
33
- | [packages/kotlin/](packages/kotlin/) | Kotlin bindings for the JVM and Android |
34
- | [packages/ts/react-native/](packages/ts/react-native/) | React Native TurboModule, native packaging and mobile builds |
35
- | [packages/ts/test/](packages/ts/test/) | Browser integration tests |
36
- | [examples/rust/](examples/rust/) | Native orbs, identity, execution and resource lifetime |
26
+ | Directory | Contents |
27
+ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
28
+ | [crates/core/](crates/core/) | Shared Rust engine for ownership, state revisions and orb updates |
29
+ | [crates/tembra/](crates/tembra/) | Single Rust facade for native and isolated Wasm orbs |
30
+ | [crates/bridge/](crates/bridge/) | Communication between the engine and its platform integrations |
31
+ | [crates/contracts/](crates/contracts/) | WIT contracts, orb artifacts and installation grants |
32
+ | [crates/executor-wasm/](crates/executor-wasm/) | Runs orb artifacts in Wasmtime for Rust hosts |
33
+ | [crates/node-binding/](crates/node-binding/) | Connects Node.js to the Rust engine |
34
+ | [crates/mobile/](crates/mobile/) | Shared Rust kernel bindings for Swift and Kotlin |
35
+ | [crates/browser-wasm/](crates/browser-wasm/) | Makes the Rust engine available in browsers and Workers |
36
+ | [crates/orb-macro/](crates/orb-macro/) | Derives a compiled orb's WIT contract and bindings from a Rust module |
37
+ | [crates/cargo-tembra/](crates/cargo-tembra/) | `cargo tembra`: builds, inspects and packages Rust orbs |
38
+ | [packages/ts/sdk/](packages/ts/sdk/) | TypeScript SDK and orb tooling |
39
+ | [packages/ts/engine-node/](packages/ts/engine-node/) | Native engine packaging and builds |
40
+ | [packages/ts/engine-wasm/](packages/ts/engine-wasm/) | WASM engine packaging and builds |
41
+ | [packages/swift/](packages/swift/) | Swift bindings for iOS and macOS |
42
+ | [packages/kotlin/](packages/kotlin/) | Kotlin bindings for the JVM and Android |
43
+ | [packages/ts/react-native/](packages/ts/react-native/) | React Native TurboModule, native packaging and mobile builds |
44
+ | [packages/ts/test/](packages/ts/test/) | Browser integration tests |
45
+ | [examples/rust/](examples/rust/) | Native orbs, identity, execution and resource lifetime |
46
+ | [examples/wasm-orb/](examples/wasm-orb/) | A TypeScript orb and a compiled Rust orb built from one WIT file |
47
+ | [examples/rust-orb-service/](examples/rust-orb-service/) | A compiled Rust orb exporting one service, written from its code and built with `cargo tembra` |
48
+ | [examples/rust-orb-hook-contribution/](examples/rust-orb-hook-contribution/) | A compiled Rust orb contributing to a native orb's hook, counting in a root resource |
49
+ | [examples/rust-orb-hook-declaration/](examples/rust-orb-hook-declaration/) | A compiled Rust orb declaring a hook, and another compiled Rust orb contributing to it |
50
+ | [examples/rust-orb-state/](examples/rust-orb-state/) | A compiled Rust orb whose state the kernel keeps and validates, observed and reloaded by the host |
51
+ | [examples/rust-orb-context/](examples/rust-orb-context/) | A compiled Rust orb reading its call's principal, its object's address and logging through the kernel |
52
+ | [examples/rust-orb-service-lifetime/](examples/rust-orb-service-lifetime/) | A compiled Rust orb with pinned, lingering and passing services, told apart by what survives a release |
53
+ | [examples/rust-orb-service-resource/](examples/rust-orb-service-resource/) | A compiled Rust orb whose service objects each own a resource that depends on the root's, opened and closed per object |
54
+ | [examples/rust-orb-shared-interface/](examples/rust-orb-shared-interface/) | A compiled Rust orb implementing a WIT interface shared with a native orb; the host consults both |
55
+ | [examples/rust-orb-import/](examples/rust-orb-import/) | A compiled Rust orb importing another compiled Rust orb's interface and calling it; the installer binds the two |
56
+ | [examples/rust-orb-wit-resource/](examples/rust-orb-wit-resource/) | A compiled Rust orb handing out text builders as a WIT resource, and another compiled Rust orb importing and using them |
57
+ | [examples/rust-orb-native/](examples/rust-orb-native/) | Two Rust orb crates implementing one WIT interface, linked into one native host that installs both through `orb()` |
37
58
 
38
59
  ## Development
39
60
 
61
+ The [Wasm orb example](examples/wasm-orb/README.md) builds a TypeScript orb with an npm dependency
62
+ and a compiled Rust provider, then installs both artifacts in a Node host. The
63
+ [Rust orb example](examples/rust-orb-service/README.md) writes a compiled orb from a Rust module with
64
+ `#[orb]` and builds its artifact with `cargo tembra`.
65
+
40
66
  See the [guide](docs/README.md) for concepts and Rust and TypeScript usage.
41
67
  See [DEVELOP.md](DEVELOP.md) for setup, tools, builds, tests and technical details.
42
68
  See [CONTRIBUTING.md](CONTRIBUTING.md) for code structure and documentation conventions.
@@ -0,0 +1,2 @@
1
+ /** Return a new URL for the interpreter core module shipped next to this module. */
2
+ export declare function interpreterURL(): URL;
package/dist/assets.js ADDED
@@ -0,0 +1,7 @@
1
+ // assets.ts
2
+ function interpreterURL() {
3
+ return new URL("./interpreter/interpreter.wasm", import.meta.url);
4
+ }
5
+ export {
6
+ interpreterURL
7
+ };
@@ -0,0 +1,140 @@
1
+ /* tslint:disable */
2
+ /* eslint-disable */
3
+
4
+ /**
5
+ * Immutable artifact data shares one prepared contract across isolated installations.
6
+ */
7
+ export class WasmArtifact {
8
+ free(): void;
9
+ [Symbol.dispose](): void;
10
+ /**
11
+ * Bind an export (by interface identity) or import (by world binding) method once.
12
+ */
13
+ bind(binding: string, method: string, exports: boolean): number;
14
+ /**
15
+ * Read identity without copying the implementation through JSON.
16
+ */
17
+ description(): string;
18
+ /**
19
+ * Decode and re-validate the prepared contract before a browser creates any guest authority.
20
+ */
21
+ constructor(bytes: Uint8Array);
22
+ /**
23
+ * Answer the typed install-time queries: `install`, `implementation` and `describe`.
24
+ */
25
+ request(packet: string): string;
26
+ /**
27
+ * Copy source once when creating a fresh interpreter heap.
28
+ */
29
+ source(): string;
30
+ /**
31
+ * Validate a JSON argument tuple or result through a bound slot; returns the ok/error envelope.
32
+ */
33
+ validate(slot: number, _arguments: boolean, value: string): string;
34
+ }
35
+
36
+ /**
37
+ * Metadata of a compiled Orb whose exact bytes a host-trusted prepared adapter was built from.
38
+ *
39
+ * Native tooling verified the component's real WIT types against this contract before it
40
+ * generated the adapter; the browser only re-checks the binding by digest. It answers the same
41
+ * install-time queries as [`WasmArtifact`] and carries no executable payload.
42
+ */
43
+ export class WasmPreparedComponent {
44
+ free(): void;
45
+ [Symbol.dispose](): void;
46
+ /**
47
+ * Bind an export (by interface identity) or import (by world binding) method once.
48
+ */
49
+ bind(binding: string, method: string, exports: boolean): number;
50
+ /**
51
+ * Compiled contribution roles and their priorities, as a JSON object.
52
+ */
53
+ contributions(): string;
54
+ /**
55
+ * Read identity as `WasmArtifact.description` does, with kind `component`.
56
+ */
57
+ description(): string;
58
+ /**
59
+ * The lowercase hexadecimal SHA-256 digest that selected the adapter.
60
+ */
61
+ digest(): string;
62
+ /**
63
+ * Declared hooks and their composition (`series`, `waterfall`, `bail`), as a JSON object.
64
+ */
65
+ hooks(): string;
66
+ /**
67
+ * Hash `bytes` and decode their metadata only when the digest is one of `digests`, the
68
+ * SHA-256 digests of the application's registered prepared adapters.
69
+ */
70
+ constructor(bytes: Uint8Array, digests: string[]);
71
+ /**
72
+ * Answer the typed install-time queries: `install`, `implementation` and `describe`.
73
+ */
74
+ request(packet: string): string;
75
+ /**
76
+ * Service policies (`lifetime`, `linger_ms`) by exported interface, as a JSON object.
77
+ */
78
+ services(): string;
79
+ /**
80
+ * Validate a JSON argument tuple or result through a bound slot; returns the ok/error envelope.
81
+ */
82
+ validate(slot: number, _arguments: boolean, value: string): string;
83
+ }
84
+
85
+ /**
86
+ * Whether `bytes` claim a compiled component (Orb metadata without a source bundle).
87
+ *
88
+ * A cheap container scan that selects the browser execution path; it grants nothing.
89
+ */
90
+ export function compiledArtifact(bytes: Uint8Array): boolean;
91
+
92
+ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
93
+
94
+ export interface InitOutput {
95
+ readonly memory: WebAssembly.Memory;
96
+ readonly __wbg_wasmartifact_free: (a: number, b: number) => void;
97
+ readonly __wbg_wasmpreparedcomponent_free: (a: number, b: number) => void;
98
+ readonly compiledArtifact: (a: number, b: number) => number;
99
+ readonly wasmartifact_bind: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
100
+ readonly wasmartifact_description: (a: number, b: number) => void;
101
+ readonly wasmartifact_new: (a: number, b: number, c: number) => void;
102
+ readonly wasmartifact_request: (a: number, b: number, c: number, d: number) => void;
103
+ readonly wasmartifact_source: (a: number, b: number) => void;
104
+ readonly wasmartifact_validate: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
105
+ readonly wasmpreparedcomponent_bind: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
106
+ readonly wasmpreparedcomponent_contributions: (a: number, b: number) => void;
107
+ readonly wasmpreparedcomponent_description: (a: number, b: number) => void;
108
+ readonly wasmpreparedcomponent_digest: (a: number, b: number) => void;
109
+ readonly wasmpreparedcomponent_hooks: (a: number, b: number) => void;
110
+ readonly wasmpreparedcomponent_new: (a: number, b: number, c: number, d: number, e: number) => void;
111
+ readonly wasmpreparedcomponent_request: (a: number, b: number, c: number, d: number) => void;
112
+ readonly wasmpreparedcomponent_services: (a: number, b: number) => void;
113
+ readonly wasmpreparedcomponent_validate: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
114
+ readonly __wbindgen_export: (a: number, b: number) => number;
115
+ readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
116
+ readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
117
+ readonly __wbindgen_export3: (a: number, b: number, c: number) => void;
118
+ }
119
+
120
+ export type SyncInitInput = BufferSource | WebAssembly.Module;
121
+
122
+ /**
123
+ * Instantiates the given `module`, which can either be bytes or
124
+ * a precompiled `WebAssembly.Module`.
125
+ *
126
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
127
+ *
128
+ * @returns {InitOutput}
129
+ */
130
+ export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
131
+
132
+ /**
133
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
134
+ * for everything else, calls `WebAssembly.instantiate` directly.
135
+ *
136
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
137
+ *
138
+ * @returns {Promise<InitOutput>}
139
+ */
140
+ export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;