@syntropika/tembra-sdk 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.
Files changed (241) hide show
  1. package/README.md +43 -17
  2. package/dist/authoring/types.d.ts +64 -3
  3. package/dist/authoring/wit.d.ts +6 -0
  4. package/dist/bridge/commands.d.ts +1190 -0
  5. package/dist/bridge/identifiers.d.ts +2 -0
  6. package/dist/bridge/kernel.d.ts +18 -107
  7. package/dist/bridge/protocol.d.ts +3 -138
  8. package/dist/browser.d.ts +14 -1
  9. package/dist/browser.js +141 -3332
  10. package/dist/chunks/browser-b8jamxw2.js +3399 -0
  11. package/dist/chunks/execution-nsqc6nrt.js +1419 -0
  12. package/dist/chunks/index-01zk0xqx.js +160 -0
  13. package/dist/chunks/index-3fjdfdfd.js +152 -0
  14. package/dist/chunks/index-aaymjn7v.js +787 -0
  15. package/dist/chunks/index-c1w7z9hx.js +356 -0
  16. package/dist/chunks/index-h8t0n42q.js +738 -0
  17. package/dist/chunks/index-hfds9mzp.js +308 -0
  18. package/dist/chunks/index-kr4x67wt.js +177 -0
  19. package/dist/chunks/index-kr6bnh34.js +117 -0
  20. package/dist/chunks/index-kyt9dj0a.js +1421 -0
  21. package/dist/chunks/index-n1wxzc9w.js +830 -0
  22. package/dist/chunks/index-pvac426d.js +74 -0
  23. package/dist/chunks/index-smyds5ce.js +3234 -0
  24. package/dist/chunks/index-sse8aapb.js +121 -0
  25. package/dist/chunks/index-v6heph77.js +643 -0
  26. package/dist/chunks/index-xrdvnv37.js +3448 -0
  27. package/dist/chunks/index-za4mg94e.js +26 -0
  28. package/dist/chunks/index-zkqmnjj8.js +167 -0
  29. package/dist/coordinator.js +9 -500
  30. package/dist/error.d.ts +2 -0
  31. package/dist/errors.d.ts +3 -0
  32. package/dist/guest.d.ts +173 -0
  33. package/dist/guest.js +26 -0
  34. package/dist/host.d.ts +36 -30
  35. package/dist/host.js +37 -3310
  36. package/dist/http/bytes.d.ts +8 -0
  37. package/dist/http/events.d.ts +7 -0
  38. package/dist/http.d.ts +45 -0
  39. package/dist/http.js +291 -0
  40. package/dist/index.d.ts +2 -0
  41. package/dist/index.js +49 -862
  42. package/dist/infrastructure/rpc/client.d.ts +2 -1
  43. package/dist/infrastructure/rpc/resources.d.ts +28 -0
  44. package/dist/interpreter/abi.d.ts +54 -0
  45. package/dist/interpreter/acquire.d.ts +18 -0
  46. package/dist/interpreter/browser-network.d.ts +52 -0
  47. package/dist/interpreter/browser-port.d.ts +55 -0
  48. package/dist/interpreter/browser.d.ts +79 -0
  49. package/dist/interpreter/cli.d.ts +5 -0
  50. package/dist/interpreter/codec.d.ts +42 -0
  51. package/dist/interpreter/component/execution.d.ts +42 -0
  52. package/dist/interpreter/component/host.d.ts +69 -0
  53. package/dist/interpreter/component/instance.d.ts +40 -0
  54. package/dist/interpreter/component/kernel.d.ts +120 -0
  55. package/dist/interpreter/component/names.d.ts +5 -0
  56. package/dist/interpreter/component/port.d.ts +85 -0
  57. package/dist/interpreter/component/prepared.d.ts +97 -0
  58. package/dist/interpreter/component/resources.d.ts +45 -0
  59. package/dist/interpreter/component/revision.d.ts +87 -0
  60. package/dist/interpreter/component/scope.d.ts +116 -0
  61. package/dist/interpreter/component/streams.d.ts +28 -0
  62. package/dist/interpreter/component/values.d.ts +79 -0
  63. package/dist/interpreter/component/wasi-filesystem.d.ts +21 -0
  64. package/dist/interpreter/component/wasi-host.d.ts +64 -0
  65. package/dist/interpreter/component/wasi-http.d.ts +33 -0
  66. package/dist/interpreter/component/wasi-sockets.d.ts +183 -0
  67. package/dist/interpreter/component/wasi.d.ts +41 -0
  68. package/dist/interpreter/core.d.ts +64 -0
  69. package/dist/interpreter/fetch-http-provider.d.ts +17 -0
  70. package/dist/interpreter/filesystem/contract.d.ts +85 -0
  71. package/dist/interpreter/filesystem/memory.d.ts +3 -0
  72. package/dist/interpreter/filesystem/opfs.d.ts +3 -0
  73. package/dist/interpreter/filesystem/scope.d.ts +35 -0
  74. package/dist/interpreter/filesystem.d.ts +8 -0
  75. package/dist/interpreter/gate.d.ts +6 -0
  76. package/dist/interpreter/host-protocol.d.ts +100 -0
  77. package/dist/interpreter/http-ingress-fetch.d.ts +7 -0
  78. package/dist/interpreter/http-ingress.d.ts +96 -0
  79. package/dist/interpreter/http-provider.d.ts +85 -0
  80. package/dist/interpreter/io.d.ts +20 -0
  81. package/dist/interpreter/mobile.d.ts +149 -0
  82. package/dist/interpreter/native-ingress.d.ts +95 -0
  83. package/dist/interpreter/node-port.d.ts +25 -0
  84. package/dist/interpreter/node.d.ts +36 -0
  85. package/dist/interpreter/revision.d.ts +64 -0
  86. package/dist/interpreter/scope.d.ts +89 -0
  87. package/dist/interpreter/socket-addresses.d.ts +50 -0
  88. package/dist/interpreter/socket-provider.d.ts +110 -0
  89. package/dist/interpreter/standard-cli.d.ts +34 -0
  90. package/dist/interpreter/standard-codec.d.ts +96 -0
  91. package/dist/interpreter/standard-filesystem.d.ts +47 -0
  92. package/dist/interpreter/standard-host.d.ts +71 -0
  93. package/dist/interpreter/standard-http-values.d.ts +159 -0
  94. package/dist/interpreter/standard-http.d.ts +9 -0
  95. package/dist/interpreter/standard-ingress.d.ts +63 -0
  96. package/dist/interpreter/standard-sockets.d.ts +177 -0
  97. package/dist/interpreter/standard-streams.d.ts +218 -0
  98. package/dist/interpreter/standard-system.d.ts +35 -0
  99. package/dist/interpreter/standard-utf8.d.ts +4 -0
  100. package/dist/interpreter/standard.d.ts +18 -0
  101. package/dist/interpreter/types.d.ts +152 -0
  102. package/dist/interpreter/wit-shape.d.ts +92 -0
  103. package/dist/manager.js +5 -332
  104. package/dist/msgpack.js +9 -615
  105. package/dist/node.d.ts +8 -1
  106. package/dist/node.js +248 -3321
  107. package/dist/rpc.js +196 -699
  108. package/dist/runtime/adapters.d.ts +120 -0
  109. package/dist/runtime/adapters.js +38 -0
  110. package/dist/runtime/calls.d.ts +7 -6
  111. package/dist/runtime/lifecycle.d.ts +3 -1
  112. package/dist/runtime/orbs.d.ts +5 -4
  113. package/dist/runtime/references.d.ts +27 -1
  114. package/dist/runtime/reload.d.ts +5 -3
  115. package/dist/runtime/scopes.d.ts +1 -1
  116. package/dist/runtime/signals.d.ts +4 -0
  117. package/dist/runtime/wit-client.d.ts +38 -0
  118. package/dist/telemetry.js +4 -25
  119. package/dist/tooling/build.d.ts +2 -2
  120. package/dist/tooling/client-resources.d.ts +23 -0
  121. package/dist/tooling/client.d.ts +10 -0
  122. package/dist/tooling/component-glue.d.ts +17 -0
  123. package/dist/tooling/component.d.ts +11 -0
  124. package/dist/tooling/index.d.ts +3 -1
  125. package/dist/tooling/index.js +1155 -102
  126. package/dist/tooling/resolver.d.ts +4 -4
  127. package/dist/tooling/typecheck.d.ts +2 -1
  128. package/dist/tooling/types.d.ts +27 -12
  129. package/dist/tooling/wit.d.ts +9 -0
  130. package/dist/wasi/wasi-clocks-types.d.ts +2 -0
  131. package/dist/wasi/wasi-http-client.d.ts +5 -0
  132. package/dist/wasi/wasi-http-types.d.ts +285 -0
  133. package/dist/wasi/wasi-sockets-ip-name-lookup.d.ts +23 -0
  134. package/dist/wasi/wasi-sockets-types.d.ts +146 -0
  135. package/package.json +62 -35
  136. package/src/authoring/declaration.ts +1 -1
  137. package/src/authoring/types.ts +53 -3
  138. package/src/authoring/wit.ts +15 -0
  139. package/src/bridge/commands.ts +1105 -0
  140. package/src/bridge/identifiers.ts +2 -0
  141. package/src/bridge/kernel.ts +56 -98
  142. package/src/bridge/protocol.ts +3 -142
  143. package/src/browser.ts +90 -6
  144. package/src/context-key.ts +4 -7
  145. package/src/error.ts +1 -1
  146. package/src/errors.ts +7 -0
  147. package/src/guest.ts +327 -0
  148. package/src/host.ts +128 -23
  149. package/src/http/bytes.ts +87 -0
  150. package/src/http/events.ts +34 -0
  151. package/src/http.ts +272 -0
  152. package/src/index.ts +3 -0
  153. package/src/infrastructure/rpc/client.ts +136 -17
  154. package/src/infrastructure/rpc/resources.ts +123 -0
  155. package/src/interpreter/abi.ts +69 -0
  156. package/src/interpreter/acquire.ts +58 -0
  157. package/src/interpreter/browser-network.ts +170 -0
  158. package/src/interpreter/browser-port.ts +425 -0
  159. package/src/interpreter/browser.ts +340 -0
  160. package/src/interpreter/cli.ts +30 -0
  161. package/src/interpreter/codec.ts +298 -0
  162. package/src/interpreter/component/execution.ts +264 -0
  163. package/src/interpreter/component/host.ts +409 -0
  164. package/src/interpreter/component/instance.ts +138 -0
  165. package/src/interpreter/component/kernel.ts +611 -0
  166. package/src/interpreter/component/names.ts +13 -0
  167. package/src/interpreter/component/port.ts +598 -0
  168. package/src/interpreter/component/prepared.ts +194 -0
  169. package/src/interpreter/component/resources.ts +345 -0
  170. package/src/interpreter/component/revision.ts +702 -0
  171. package/src/interpreter/component/scope.ts +447 -0
  172. package/src/interpreter/component/streams.ts +180 -0
  173. package/src/interpreter/component/values.ts +254 -0
  174. package/src/interpreter/component/wasi-filesystem.ts +472 -0
  175. package/src/interpreter/component/wasi-host.ts +197 -0
  176. package/src/interpreter/component/wasi-http.ts +939 -0
  177. package/src/interpreter/component/wasi-sockets.ts +958 -0
  178. package/src/interpreter/component/wasi.ts +238 -0
  179. package/src/interpreter/core.ts +386 -0
  180. package/src/interpreter/fetch-http-provider.ts +98 -0
  181. package/src/interpreter/filesystem/contract.ts +138 -0
  182. package/src/interpreter/filesystem/memory.ts +180 -0
  183. package/src/interpreter/filesystem/opfs.ts +294 -0
  184. package/src/interpreter/filesystem/scope.ts +390 -0
  185. package/src/interpreter/filesystem.ts +20 -0
  186. package/src/interpreter/gate.ts +55 -0
  187. package/src/interpreter/host-protocol.ts +242 -0
  188. package/src/interpreter/http-ingress-fetch.ts +133 -0
  189. package/src/interpreter/http-ingress.ts +203 -0
  190. package/src/interpreter/http-provider.ts +105 -0
  191. package/src/interpreter/io.ts +66 -0
  192. package/src/interpreter/mobile.ts +385 -0
  193. package/src/interpreter/native-ingress.ts +550 -0
  194. package/src/interpreter/node-port.ts +218 -0
  195. package/src/interpreter/node.ts +114 -0
  196. package/src/interpreter/revision.ts +450 -0
  197. package/src/interpreter/scope.ts +453 -0
  198. package/src/interpreter/socket-addresses.ts +246 -0
  199. package/src/interpreter/socket-provider.ts +126 -0
  200. package/src/interpreter/standard-cli.ts +184 -0
  201. package/src/interpreter/standard-codec.ts +403 -0
  202. package/src/interpreter/standard-filesystem.ts +545 -0
  203. package/src/interpreter/standard-host.ts +840 -0
  204. package/src/interpreter/standard-http-values.ts +624 -0
  205. package/src/interpreter/standard-http.ts +622 -0
  206. package/src/interpreter/standard-ingress.ts +344 -0
  207. package/src/interpreter/standard-sockets.ts +847 -0
  208. package/src/interpreter/standard-streams.ts +710 -0
  209. package/src/interpreter/standard-system.ts +182 -0
  210. package/src/interpreter/standard-utf8.ts +72 -0
  211. package/src/interpreter/standard.ts +283 -0
  212. package/src/interpreter/types.ts +163 -0
  213. package/src/interpreter/wit-shape.ts +175 -0
  214. package/src/node.ts +43 -14
  215. package/src/runtime/activities.ts +6 -6
  216. package/src/runtime/adapters.ts +314 -0
  217. package/src/runtime/calls.ts +213 -90
  218. package/src/runtime/context.ts +7 -7
  219. package/src/runtime/lifecycle.ts +36 -17
  220. package/src/runtime/orbs.ts +81 -39
  221. package/src/runtime/programs.ts +16 -8
  222. package/src/runtime/references.ts +128 -11
  223. package/src/runtime/reload.ts +71 -30
  224. package/src/runtime/resources.ts +2 -2
  225. package/src/runtime/scopes.ts +17 -17
  226. package/src/runtime/session.ts +3 -1
  227. package/src/runtime/signals.ts +31 -0
  228. package/src/runtime/wit-client.ts +228 -0
  229. package/src/tooling/build.ts +152 -54
  230. package/src/tooling/client-resources.ts +74 -0
  231. package/src/tooling/client.ts +531 -0
  232. package/src/tooling/component-glue.ts +288 -0
  233. package/src/tooling/component.ts +225 -0
  234. package/src/tooling/index.ts +3 -7
  235. package/src/tooling/resolver.ts +42 -25
  236. package/src/tooling/typecheck.ts +59 -4
  237. package/src/tooling/types.ts +27 -12
  238. package/src/tooling/wit.ts +188 -0
  239. package/dist/embedded.d.ts +0 -1
  240. package/dist/embedded.js +0 -1
  241. package/src/embedded.ts +0 -301
@@ -0,0 +1,98 @@
1
+ /** WHATWG Fetch implementation of the host HTTP contract, with explicit platform limits. */
2
+ import { byteString, bytesOf, HttpProviderError, type HttpProvider } from "./http-provider.ts";
3
+
4
+ /** The largest request body `fetchHttpProvider` buffers before calling Fetch. */
5
+ export const FETCH_BODY_BYTES = 8 << 20;
6
+ /** Methods Fetch refuses to send. */
7
+ const FETCH_FORBIDDEN_METHODS = new Set(["CONNECT", "TRACE", "TRACK"]);
8
+
9
+ const unsupported = (message: string) =>
10
+ new HttpProviderError({ tag: "internal-error", val: message }, message);
11
+
12
+ /** Fetch needs the whole upload before it starts; collect it under `FETCH_BODY_BYTES`. */
13
+ async function collect(body: ReadableStream<Uint8Array>): Promise<Uint8Array> {
14
+ const reader = body.getReader();
15
+ const chunks: Uint8Array[] = [];
16
+ let total = 0;
17
+ for (let next = await reader.read(); !next.done; next = await reader.read()) {
18
+ total += next.value.byteLength;
19
+ if (total > FETCH_BODY_BYTES) {
20
+ const error = new HttpProviderError({ tag: "HTTP-request-body-size", val: BigInt(total) });
21
+ // The reason becomes the upload's outcome.
22
+ await reader.cancel(error);
23
+ throw error;
24
+ }
25
+ chunks.push(next.value);
26
+ }
27
+ const bytes = new Uint8Array(total);
28
+ let offset = 0;
29
+ for (const chunk of chunks) {
30
+ bytes.set(chunk, offset);
31
+ offset += chunk.byteLength;
32
+ }
33
+ return bytes;
34
+ }
35
+
36
+ /**
37
+ * Adapt Fetch (by default the global one) to `HttpProvider`. Fetch owns DNS, TLS and
38
+ * connections. Its platform limits are explicit errors, never emulation:
39
+ * - the upload is buffered (at most `FETCH_BODY_BYTES`) and sent after its trailers settled,
40
+ * so there is no duplex; non-empty request trailers are refused;
41
+ * - responses have no trailers, and Fetch combines duplicate response fields;
42
+ * - there is no separate connect phase: a `connect` timeout is refused;
43
+ * - `redirect: "manual"` never follows a redirect, and the opaque result is refused;
44
+ * - `CONNECT`/`TRACE`/`TRACK`, and a body with `GET` or `HEAD`, are refused;
45
+ * - credentials are omitted, and browsers silently drop their forbidden request fields;
46
+ * - Fetch sends `request.url`, whose path is WHATWG-normalized, not the raw `pathWithQuery`.
47
+ */
48
+ export function fetchHttpProvider(
49
+ fetch: (input: URL, init: RequestInit) => Promise<Response> = (input, init) =>
50
+ globalThis.fetch(input, init),
51
+ ): HttpProvider {
52
+ return {
53
+ async send(request) {
54
+ if (FETCH_FORBIDDEN_METHODS.has(request.method.toUpperCase()))
55
+ throw new HttpProviderError({ tag: "HTTP-request-method-invalid" });
56
+ if (request.timeouts.connect !== undefined)
57
+ throw unsupported("browser Fetch has no separate connect timeout");
58
+ const body = request.body ? await collect(request.body) : new Uint8Array();
59
+ if ((await request.trailers)?.length)
60
+ throw unsupported("browser Fetch cannot send request trailers");
61
+ if (body.length && (request.method === "GET" || request.method === "HEAD"))
62
+ throw unsupported(`browser Fetch cannot send a body with ${request.method}`);
63
+ const headers = new Headers();
64
+ try {
65
+ for (const [name, value] of request.fields) headers.append(name, byteString(value));
66
+ } catch (error) {
67
+ throw unsupported(error instanceof Error ? error.message : String(error));
68
+ }
69
+ let response: Response;
70
+ try {
71
+ response = await fetch(request.url, {
72
+ method: request.method,
73
+ headers,
74
+ credentials: "omit",
75
+ redirect: "manual",
76
+ signal: request.signal,
77
+ ...(body.length ? { body: body as Uint8Array<ArrayBuffer> } : {}),
78
+ });
79
+ } catch (error) {
80
+ if (request.signal.aborted || error instanceof HttpProviderError) throw error;
81
+ throw unsupported(error instanceof Error ? error.message : String(error));
82
+ }
83
+ if (response.type === "opaqueredirect" || response.redirected) {
84
+ await response.body?.cancel().catch(() => {});
85
+ throw unsupported(
86
+ response.redirected
87
+ ? "the Fetch implementation followed a redirect"
88
+ : "browser Fetch exposes redirect responses only as opaque responses",
89
+ );
90
+ }
91
+ return {
92
+ status: response.status,
93
+ fields: [...response.headers].map(([name, value]) => [name, bytesOf(value)] as const),
94
+ body: response.body,
95
+ };
96
+ },
97
+ };
98
+ }
@@ -0,0 +1,138 @@
1
+ /** Every standard `wasi:filesystem` `error-code` case except `other`; other failures surface as `io`. */
2
+ export type FilesystemErrorCode =
3
+ | "access"
4
+ | "already"
5
+ | "bad-descriptor"
6
+ | "busy"
7
+ | "deadlock"
8
+ | "quota"
9
+ | "exist"
10
+ | "file-too-large"
11
+ | "illegal-byte-sequence"
12
+ | "in-progress"
13
+ | "interrupted"
14
+ | "invalid"
15
+ | "io"
16
+ | "is-directory"
17
+ | "loop"
18
+ | "too-many-links"
19
+ | "message-size"
20
+ | "name-too-long"
21
+ | "no-device"
22
+ | "no-entry"
23
+ | "no-lock"
24
+ | "insufficient-memory"
25
+ | "insufficient-space"
26
+ | "not-directory"
27
+ | "not-empty"
28
+ | "not-recoverable"
29
+ | "unsupported"
30
+ | "no-tty"
31
+ | "no-such-device"
32
+ | "overflow"
33
+ | "not-permitted"
34
+ | "pipe"
35
+ | "read-only"
36
+ | "invalid-seek"
37
+ | "text-file-busy"
38
+ | "cross-device";
39
+
40
+ /** A provider failure carrying the WASI `error-code` that standard filesystem calls return. */
41
+ export class FilesystemError extends Error {
42
+ constructor(
43
+ readonly code: FilesystemErrorCode,
44
+ message: string = code,
45
+ ) {
46
+ super(message);
47
+ }
48
+ }
49
+
50
+ export type EntryType = "file" | "directory";
51
+
52
+ /** Metadata of one entry; `modified` is milliseconds since the Unix epoch when known. */
53
+ export interface FileStat {
54
+ readonly type: EntryType;
55
+ readonly size: bigint;
56
+ readonly modified?: number;
57
+ }
58
+
59
+ export interface DirectoryEntry {
60
+ readonly name: string;
61
+ readonly type: EntryType;
62
+ }
63
+
64
+ /** `open-at` flags plus the requested write right (`write` or `mutate-directory`). */
65
+ export interface OpenOptions {
66
+ readonly create?: boolean;
67
+ readonly exclusive?: boolean;
68
+ readonly truncate?: boolean;
69
+ readonly directory?: boolean;
70
+ readonly write?: boolean;
71
+ }
72
+
73
+ interface DescriptorBase {
74
+ readonly type: EntryType;
75
+ /** Write (file) or mutate-directory (directory) right of this descriptor. */
76
+ readonly writable: boolean;
77
+ stat(): Promise<FileStat>;
78
+ isSameObject(other: Descriptor): Promise<boolean>;
79
+ sync(): Promise<void>;
80
+ /** Idempotent; later calls fail with `bad-descriptor` while in-flight calls settle normally. */
81
+ close(): void;
82
+ }
83
+
84
+ /** An opened regular file; it follows its entry across rename where the platform allows. */
85
+ export interface FileDescriptor extends DescriptorBase {
86
+ readonly type: "file";
87
+ /** Read at most `length` bytes at `offset`; an empty result is end of file. */
88
+ read(offset: bigint, length: number): Promise<Uint8Array>;
89
+ /** Write every byte at `offset`, zero-filling any gap; `data` must stay unchanged until settled. */
90
+ write(offset: bigint, data: Uint8Array): Promise<void>;
91
+ /** Write every byte at the current end of file. */
92
+ append(data: Uint8Array): Promise<void>;
93
+ /** Truncate or zero-extend. */
94
+ setSize(size: bigint): Promise<void>;
95
+ /**
96
+ * Optional; built-in providers implement it. Write sequential chunks from `offset`, or from the
97
+ * end of file when it is absent (`append-via-stream`). The next chunk is requested only after
98
+ * the previous one is written; early exits call the iterator's `return()`. Accepted chunks are
99
+ * kept when the producer fails or the descriptor closes. OPFS commits once when the iterable
100
+ * ends, and readers observe the previous committed content until then.
101
+ */
102
+ writeStream?(chunks: AsyncIterable<Uint8Array>, offset?: bigint): Promise<void>;
103
+ }
104
+
105
+ /** An opened directory; relative paths resolve from it and never above it. */
106
+ export interface DirectoryDescriptor extends DescriptorBase {
107
+ readonly type: "directory";
108
+ openAt(path: string, options?: OpenOptions): Promise<Descriptor>;
109
+ statAt(path: string): Promise<FileStat>;
110
+ /** Lazy entries in platform order, without `.` and `..`. */
111
+ readDirectory(): AsyncIterableIterator<DirectoryEntry>;
112
+ createDirectoryAt(path: string): Promise<void>;
113
+ removeDirectoryAt(path: string): Promise<void>;
114
+ unlinkFileAt(path: string): Promise<void>;
115
+ /** POSIX `renameat`; `newDirectory` must be an open descriptor of the same storage. */
116
+ renameAt(oldPath: string, newDirectory: DirectoryDescriptor, newPath: string): Promise<void>;
117
+ }
118
+
119
+ export type Descriptor = FileDescriptor | DirectoryDescriptor;
120
+
121
+ /** One grant's permission and lifetime scope over the provider's shared storage. */
122
+ export interface MountedFilesystem {
123
+ readonly writable: boolean;
124
+ /** A new owned descriptor for the mount root. */
125
+ openRoot(): DirectoryDescriptor;
126
+ /** Close every descriptor of this scope now; settles after its in-flight calls settle. */
127
+ dispose(): Promise<void>;
128
+ }
129
+
130
+ export interface FilesystemProvider {
131
+ /** Open independent permission and lifetime scopes over explicitly shared storage. */
132
+ open(mount: string, writable: boolean): MountedFilesystem;
133
+ }
134
+
135
+ /** Throw the standard error for `code`; shared by the private provider modules. */
136
+ export function fail(code: FilesystemErrorCode, message?: string): never {
137
+ throw new FilesystemError(code, message);
138
+ }
@@ -0,0 +1,180 @@
1
+ import { type FilesystemProvider, fail } from "./contract.ts";
2
+ import { type Store, provider } from "./scope.ts";
3
+
4
+ // Memory storage: real directory nodes and file nodes with growable capacity.
5
+
6
+ const MEMORY_LIMIT = 2 ** 31 - 1;
7
+
8
+ class MemoryFile {
9
+ readonly type = "file";
10
+ data: Uint8Array = new Uint8Array(0);
11
+ size = 0;
12
+ modified = Date.now();
13
+ }
14
+
15
+ class MemoryDirectory {
16
+ readonly type = "directory";
17
+ readonly children = new Map<string, MemoryNode>();
18
+ modified = Date.now();
19
+ /** Removed directories accept no new entries; open descriptors keep the node. */
20
+ removed = false;
21
+ /** Set while attached; used to reject moving a directory into its own subtree. */
22
+ constructor(public parent: MemoryDirectory | undefined) {}
23
+ }
24
+
25
+ type MemoryNode = MemoryFile | MemoryDirectory;
26
+
27
+ function allocate(length: number): Uint8Array {
28
+ try {
29
+ return new Uint8Array(length);
30
+ } catch {
31
+ return fail("insufficient-memory", "Memory file allocation failed");
32
+ }
33
+ }
34
+
35
+ /** Grow capacity geometrically so repeated appends copy amortized O(size) bytes. */
36
+ function reserve(file: MemoryFile, end: number): void {
37
+ if (end <= file.data.length) return;
38
+ const next = allocate(Math.max(end, Math.min(MEMORY_LIMIT, file.data.length * 2 || 64)));
39
+ next.set(file.data.subarray(0, file.size));
40
+ file.data = next;
41
+ }
42
+
43
+ function child(parent: MemoryDirectory, name: string): MemoryNode {
44
+ return parent.children.get(name) ?? fail("no-entry", "No such file or directory");
45
+ }
46
+
47
+ function attach(parent: MemoryDirectory, name: string, node: MemoryNode): void {
48
+ if (parent.removed) fail("no-entry", "Directory was removed");
49
+ parent.children.set(name, node);
50
+ if (node.type === "directory") node.parent = parent;
51
+ parent.modified = Date.now();
52
+ }
53
+
54
+ function detach(parent: MemoryDirectory, name: string, node: MemoryNode): void {
55
+ parent.children.delete(name);
56
+ parent.modified = Date.now();
57
+ if (node.type === "directory") {
58
+ node.parent = undefined;
59
+ node.removed = true;
60
+ }
61
+ }
62
+
63
+ function memoryStore(root: MemoryDirectory): Store<MemoryNode> {
64
+ const directory = (node: MemoryNode) => node as MemoryDirectory;
65
+ const file = (node: MemoryNode) => node as MemoryFile;
66
+ // Each operation completes synchronously, so memory mutations are atomic.
67
+ return {
68
+ root,
69
+ limit: MEMORY_LIMIT,
70
+ type: (node) => node.type,
71
+ lookup: async (parent, name) => child(directory(parent), name),
72
+ async create(parent, name, type) {
73
+ const into = directory(parent);
74
+ if (into.children.has(name)) fail("exist", "Entry already exists");
75
+ const node = type === "file" ? new MemoryFile() : new MemoryDirectory(into);
76
+ attach(into, name, node);
77
+ return node;
78
+ },
79
+ retain: async (node) => node,
80
+ release() {},
81
+ async stat(node) {
82
+ return node.type === "file"
83
+ ? { type: "file", size: BigInt(node.size), modified: node.modified }
84
+ : { type: "directory", size: 0n, modified: node.modified };
85
+ },
86
+ same: async (a, b) => a === b,
87
+ // Iterates the live map lazily; entries added or removed meanwhile follow Map semantics.
88
+ async *entries(node) {
89
+ for (const [name, entry] of directory(node).children) yield { name, type: entry.type };
90
+ },
91
+ async read(node, offset, length) {
92
+ const target = file(node);
93
+ if (offset >= target.size) return new Uint8Array(0);
94
+ return target.data.slice(offset, Math.min(target.size, offset + length));
95
+ },
96
+ async write(node, offset, data) {
97
+ const target = file(node);
98
+ const start = offset ?? target.size;
99
+ const end = start + data.byteLength;
100
+ if (end > MEMORY_LIMIT) fail("file-too-large", "Memory file limit exceeded");
101
+ reserve(target, end);
102
+ // Bytes between the old size and `start` are already zero; truncation zero-fills.
103
+ target.data.set(data, start);
104
+ target.size = Math.max(target.size, end);
105
+ target.modified = Date.now();
106
+ },
107
+ async resize(node, size) {
108
+ const target = file(node);
109
+ if (size < target.size) {
110
+ if (size < target.data.length / 4) {
111
+ const next = allocate(size);
112
+ next.set(target.data.subarray(0, size));
113
+ target.data = next;
114
+ } else target.data.fill(0, size, target.size);
115
+ } else reserve(target, size);
116
+ target.size = size;
117
+ target.modified = Date.now();
118
+ },
119
+ async sync() {},
120
+ async remove(parent, name, type) {
121
+ const from = directory(parent);
122
+ const node = child(from, name);
123
+ if (node.type !== type)
124
+ fail(type === "file" ? "is-directory" : "not-directory", "Entry has another type");
125
+ if (node.type === "directory" && node.children.size)
126
+ fail("not-empty", "Directory is not empty");
127
+ detach(from, name, node);
128
+ },
129
+ async rename(fromNode, fromName, toNode, toName) {
130
+ const from = directory(fromNode);
131
+ const to = directory(toNode);
132
+ const node = child(from, fromName);
133
+ if (to.removed) fail("no-entry", "Directory was removed");
134
+ const replaced = to.children.get(toName);
135
+ if (replaced === node) return;
136
+ if (node.type === "directory")
137
+ for (let ancestor: MemoryDirectory | undefined = to; ancestor; ancestor = ancestor.parent)
138
+ if (ancestor === node) fail("invalid", "Cannot move a directory into itself");
139
+ if (replaced) {
140
+ if (node.type === "file" && replaced.type === "directory")
141
+ fail("is-directory", "Target is a directory");
142
+ if (node.type === "directory" && replaced.type === "file")
143
+ fail("not-directory", "Target is not a directory");
144
+ if (replaced.type === "directory" && replaced.children.size)
145
+ fail("not-empty", "Target directory is not empty");
146
+ detach(to, toName, replaced);
147
+ }
148
+ detach(from, fromName, node);
149
+ if (node.type === "directory") node.removed = false;
150
+ attach(to, toName, node);
151
+ },
152
+ };
153
+ }
154
+
155
+ /** Supply shared ephemeral storage without granting any Orb access automatically. */
156
+ export function memoryFilesystem(
157
+ files: Readonly<Record<string, string | Uint8Array>> = {},
158
+ ): FilesystemProvider {
159
+ const root = new MemoryDirectory(undefined);
160
+ const encoder = new TextEncoder();
161
+ for (const [path, value] of Object.entries(files)) {
162
+ const segments = path.split("/");
163
+ if (segments.some((part) => !part || part === "." || part === ".." || part.includes("\0")))
164
+ throw new Error("Memory filesystem paths must be normalized relative paths");
165
+ let parent = root;
166
+ for (const segment of segments.slice(0, -1)) {
167
+ let next = parent.children.get(segment);
168
+ if (!next) attach(parent, segment, (next = new MemoryDirectory(parent)));
169
+ if (next.type !== "directory") throw new Error("Memory path overlaps a file");
170
+ parent = next;
171
+ }
172
+ const name = segments.at(-1)!;
173
+ if (parent.children.has(name)) throw new Error("Memory path overlaps a file");
174
+ const node = new MemoryFile();
175
+ node.data = typeof value === "string" ? encoder.encode(value) : value.slice();
176
+ node.size = node.data.byteLength;
177
+ attach(parent, name, node);
178
+ }
179
+ return provider(memoryStore(root));
180
+ }