@syntropika/tembra-sdk 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/README.md +47 -2
- package/dist/authoring/declaration.d.ts +47 -0
- package/dist/authoring/hooks.d.ts +11 -0
- package/dist/authoring/orb.d.ts +3 -0
- package/dist/authoring/types.d.ts +166 -0
- package/dist/bridge/identifiers.d.ts +207 -0
- package/dist/bridge/kernel.d.ts +117 -0
- package/dist/bridge/protocol.d.ts +181 -0
- package/dist/browser.d.ts +21 -0
- package/dist/browser.js +3282 -0
- package/dist/codec.d.ts +1 -0
- package/dist/codecs/json.d.ts +13 -0
- package/dist/codecs/msgpack.d.ts +3 -0
- package/dist/context-key.d.ts +35 -0
- package/dist/coordinator.d.ts +1 -0
- package/dist/coordinator.js +543 -0
- package/dist/embedded.d.ts +1 -0
- package/dist/embedded.js +1 -0
- package/dist/error.d.ts +13 -0
- package/dist/errors.d.ts +122 -0
- package/dist/hooks.d.ts +1 -0
- package/dist/host.d.ts +96 -0
- package/dist/host.js +3225 -0
- package/dist/identifiers.d.ts +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +833 -0
- package/dist/infrastructure/coordinator.d.ts +13 -0
- package/dist/infrastructure/manager.d.ts +23 -0
- package/dist/infrastructure/rpc/channel.d.ts +52 -0
- package/dist/infrastructure/rpc/client.d.ts +20 -0
- package/dist/infrastructure/rpc/server.d.ts +10 -0
- package/dist/infrastructure/rpc/state.d.ts +16 -0
- package/dist/kernel.d.ts +1 -0
- package/dist/manager.d.ts +1 -0
- package/dist/manager.js +390 -0
- package/dist/msgpack.d.ts +1 -0
- package/dist/msgpack.js +635 -0
- package/dist/node.d.ts +14 -0
- package/dist/node.js +3283 -0
- package/dist/orb.d.ts +1 -0
- package/dist/protocol.d.ts +1 -0
- package/dist/rpc.d.ts +3 -0
- package/dist/rpc.js +1036 -0
- package/dist/runtime/activities.d.ts +30 -0
- package/dist/runtime/calls.d.ts +22 -0
- package/dist/runtime/context.d.ts +37 -0
- package/dist/runtime/declaration.d.ts +1 -0
- package/dist/runtime/lifecycle.d.ts +28 -0
- package/dist/runtime/orbs.d.ts +39 -0
- package/dist/runtime/programs.d.ts +31 -0
- package/dist/runtime/records.d.ts +107 -0
- package/dist/runtime/references.d.ts +38 -0
- package/dist/runtime/reload.d.ts +17 -0
- package/dist/runtime/resources.d.ts +24 -0
- package/dist/runtime/scopes.d.ts +35 -0
- package/dist/runtime/session.d.ts +69 -0
- package/dist/state/binding.d.ts +28 -0
- package/dist/state/selection.d.ts +21 -0
- package/dist/state/types.d.ts +35 -0
- package/dist/state.d.ts +2 -0
- package/dist/telemetry.d.ts +23 -0
- package/dist/telemetry.js +27 -0
- package/dist/tooling/build.d.ts +3 -0
- package/dist/tooling/index.d.ts +2 -0
- package/dist/tooling/index.js +181 -0
- package/dist/tooling/resolver.d.ts +5 -0
- package/dist/tooling/typecheck.d.ts +2 -0
- package/dist/tooling/types.d.ts +29 -0
- package/dist/types.d.ts +1 -0
- package/dist/values.d.ts +23 -0
- package/package.json +103 -4
- package/src/authoring/declaration.ts +220 -0
- package/src/authoring/hooks.ts +101 -0
- package/src/authoring/orb.ts +77 -0
- package/src/authoring/types.ts +212 -0
- package/src/bridge/identifiers.ts +212 -0
- package/src/bridge/kernel.ts +117 -0
- package/src/bridge/protocol.ts +193 -0
- package/src/browser.ts +59 -0
- package/src/codec.ts +1 -0
- package/src/codecs/json.ts +147 -0
- package/src/codecs/msgpack.ts +26 -0
- package/src/context-key.ts +94 -0
- package/src/coordinator.ts +1 -0
- package/src/embedded.ts +293 -0
- package/src/error.ts +50 -0
- package/src/errors.ts +237 -0
- package/src/hooks.ts +1 -0
- package/src/host.ts +142 -0
- package/src/identifiers.ts +1 -0
- package/src/index.ts +22 -0
- package/src/infrastructure/coordinator.ts +76 -0
- package/src/infrastructure/manager.ts +77 -0
- package/src/infrastructure/rpc/channel.ts +88 -0
- package/src/infrastructure/rpc/client.ts +161 -0
- package/src/infrastructure/rpc/server.ts +201 -0
- package/src/infrastructure/rpc/state.ts +70 -0
- package/src/kernel.ts +1 -0
- package/src/manager.ts +1 -0
- package/src/msgpack.ts +1 -0
- package/src/node.ts +53 -0
- package/src/orb.ts +1 -0
- package/src/protocol.ts +1 -0
- package/src/rpc.ts +3 -0
- package/src/runtime/activities.ts +197 -0
- package/src/runtime/calls.ts +165 -0
- package/src/runtime/context.ts +113 -0
- package/src/runtime/declaration.ts +1 -0
- package/src/runtime/lifecycle.ts +227 -0
- package/src/runtime/orbs.ts +292 -0
- package/src/runtime/programs.ts +274 -0
- package/src/runtime/records.ts +127 -0
- package/src/runtime/references.ts +398 -0
- package/src/runtime/reload.ts +161 -0
- package/src/runtime/resources.ts +157 -0
- package/src/runtime/scopes.ts +210 -0
- package/src/runtime/session.ts +181 -0
- package/src/state/binding.ts +157 -0
- package/src/state/selection.ts +122 -0
- package/src/state/types.ts +47 -0
- package/src/state.ts +2 -0
- package/src/telemetry.ts +45 -0
- package/src/tooling/build.ts +83 -0
- package/src/tooling/index.ts +8 -0
- package/src/tooling/resolver.ts +95 -0
- package/src/tooling/typecheck.ts +32 -0
- package/src/tooling/types.ts +32 -0
- package/src/types.ts +1 -0
- package/src/values.ts +85 -0
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
/** Closed adapter vocabulary. Strings are retained only as the wire representation. */
|
|
2
|
+
type ValueOf<T> = T[keyof T];
|
|
3
|
+
|
|
4
|
+
export const KernelOp = Object.freeze({
|
|
5
|
+
ContextDerive: "context-derive",
|
|
6
|
+
ContextValue: "context-value",
|
|
7
|
+
ContextStats: "context-stats",
|
|
8
|
+
Allocate: "allocate",
|
|
9
|
+
ScopeRegister: "scope-register",
|
|
10
|
+
ScopeExists: "scope-exists",
|
|
11
|
+
ScopesForOwner: "scopes-for-owner",
|
|
12
|
+
ScopesForOrb: "scopes-for-orb",
|
|
13
|
+
ScopeAddResource: "scope-add-resource",
|
|
14
|
+
ScopeActivate: "scope-activate",
|
|
15
|
+
ScopesCleanup: "scopes-cleanup",
|
|
16
|
+
ScopesReloadRegistered: "scopes-reload-registered",
|
|
17
|
+
ScopesReload: "scopes-reload",
|
|
18
|
+
ProgramRun: "program-run",
|
|
19
|
+
ProgramNext: "program-next",
|
|
20
|
+
ProgramCompleteStep: "program-complete-step",
|
|
21
|
+
ProgramCommit: "program-commit",
|
|
22
|
+
ProgramAbort: "program-abort",
|
|
23
|
+
ProgramForget: "program-forget",
|
|
24
|
+
Features: "features",
|
|
25
|
+
Prepare: "prepare",
|
|
26
|
+
Gate: "gate",
|
|
27
|
+
GateOrbs: "gate-orbs",
|
|
28
|
+
Commit: "commit",
|
|
29
|
+
Abort: "abort",
|
|
30
|
+
Orbs: "orbs",
|
|
31
|
+
Orb: "orb",
|
|
32
|
+
OrbNamed: "orb-named",
|
|
33
|
+
NextDeadline: "next-deadline",
|
|
34
|
+
Address: "address",
|
|
35
|
+
Acquire: "acquire",
|
|
36
|
+
Ready: "ready",
|
|
37
|
+
Dependency: "dependency",
|
|
38
|
+
Undepend: "undepend",
|
|
39
|
+
Fail: "fail",
|
|
40
|
+
Status: "status",
|
|
41
|
+
Release: "release",
|
|
42
|
+
Forget: "forget",
|
|
43
|
+
Root: "root",
|
|
44
|
+
CleanupRoot: "cleanup-root",
|
|
45
|
+
RootPrincipal: "root-principal",
|
|
46
|
+
CheckContext: "check-context",
|
|
47
|
+
CheckRoot: "check-root",
|
|
48
|
+
EndRoot: "end-root",
|
|
49
|
+
CancelRoot: "cancel-root",
|
|
50
|
+
BeginCall: "begin-call",
|
|
51
|
+
BeginOperation: "begin-operation",
|
|
52
|
+
BeginHookObservation: "begin-hook-observation",
|
|
53
|
+
FinishCall: "finish-call",
|
|
54
|
+
Invocation: "invocation",
|
|
55
|
+
StateInit: "state-init",
|
|
56
|
+
Snapshot: "snapshot",
|
|
57
|
+
StateAdopt: "state-adopt",
|
|
58
|
+
Task: "task",
|
|
59
|
+
TaskRoot: "task-root",
|
|
60
|
+
StopTask: "stop-task",
|
|
61
|
+
FinishTask: "finish-task",
|
|
62
|
+
Resource: "resource",
|
|
63
|
+
ResourceOpened: "resource-opened",
|
|
64
|
+
ResourceValue: "resource-value",
|
|
65
|
+
CloseResource: "close-resource",
|
|
66
|
+
ResourceClosed: "resource-closed",
|
|
67
|
+
Disposed: "disposed",
|
|
68
|
+
Tick: "tick",
|
|
69
|
+
NextWake: "next-wake",
|
|
70
|
+
NextIdle: "next-idle",
|
|
71
|
+
Close: "close",
|
|
72
|
+
FinishClose: "finish-close",
|
|
73
|
+
Diagnostics: "diagnostics",
|
|
74
|
+
Drain: "drain",
|
|
75
|
+
Restrict: "restrict",
|
|
76
|
+
Contribute: "contribute",
|
|
77
|
+
ContributionOrdinal: "contribution-ordinal",
|
|
78
|
+
HookPlan: "hook-plan",
|
|
79
|
+
Listen: "listen",
|
|
80
|
+
Subscribe: "subscribe",
|
|
81
|
+
Enqueue: "enqueue",
|
|
82
|
+
NextDelivery: "next-delivery",
|
|
83
|
+
FinishDelivery: "finish-delivery",
|
|
84
|
+
Unsubscribe: "unsubscribe",
|
|
85
|
+
} as const);
|
|
86
|
+
export type KernelOp = ValueOf<typeof KernelOp>;
|
|
87
|
+
|
|
88
|
+
export const ActionType = Object.freeze({
|
|
89
|
+
Execute: "execute",
|
|
90
|
+
CancelEffects: "cancel-effects",
|
|
91
|
+
ProgramPrepared: "program-prepared",
|
|
92
|
+
ProgramComplete: "program-complete",
|
|
93
|
+
Dispose: "dispose",
|
|
94
|
+
CloseResource: "close-resource",
|
|
95
|
+
DropValue: "drop-value",
|
|
96
|
+
CancelRoot: "cancel-root",
|
|
97
|
+
CancelTask: "cancel-task",
|
|
98
|
+
RetireOrb: "retire-orb",
|
|
99
|
+
State: "state",
|
|
100
|
+
SubscriptionFailed: "subscription-failed",
|
|
101
|
+
DetachSubscription: "detach-subscription",
|
|
102
|
+
Deliver: "deliver",
|
|
103
|
+
} as const);
|
|
104
|
+
export type ActionType = ValueOf<typeof ActionType>;
|
|
105
|
+
|
|
106
|
+
export const EffectType = Object.freeze({
|
|
107
|
+
Stop: "stop",
|
|
108
|
+
Open: "open",
|
|
109
|
+
Close: "close",
|
|
110
|
+
Restore: "restore",
|
|
111
|
+
Prepare: "prepare",
|
|
112
|
+
Validate: "validate",
|
|
113
|
+
Initialize: "initialize",
|
|
114
|
+
Migrate: "migrate",
|
|
115
|
+
Adopt: "adopt",
|
|
116
|
+
Start: "start",
|
|
117
|
+
Drop: "drop",
|
|
118
|
+
} as const);
|
|
119
|
+
export type EffectType = ValueOf<typeof EffectType>;
|
|
120
|
+
|
|
121
|
+
export const StepType = Object.freeze({
|
|
122
|
+
Execute: "execute",
|
|
123
|
+
Wait: "wait",
|
|
124
|
+
Prepared: "prepared",
|
|
125
|
+
Complete: "complete",
|
|
126
|
+
Failed: "failed",
|
|
127
|
+
} as const);
|
|
128
|
+
export type StepType = ValueOf<typeof StepType>;
|
|
129
|
+
|
|
130
|
+
export const NativeOp = Object.freeze({
|
|
131
|
+
Activate: "activate",
|
|
132
|
+
Dispose: "dispose",
|
|
133
|
+
CancelEffect: "cancel-effect",
|
|
134
|
+
Effect: "effect",
|
|
135
|
+
Invoke: "invoke",
|
|
136
|
+
Contribute: "contribute",
|
|
137
|
+
} as const);
|
|
138
|
+
export type NativeOp = ValueOf<typeof NativeOp>;
|
|
139
|
+
|
|
140
|
+
export const RpcOp = Object.freeze({
|
|
141
|
+
Describe: "describe",
|
|
142
|
+
Get: "get",
|
|
143
|
+
Release: "release",
|
|
144
|
+
Call: "call",
|
|
145
|
+
Cancel: "cancel",
|
|
146
|
+
} as const);
|
|
147
|
+
export type RpcOp = ValueOf<typeof RpcOp>;
|
|
148
|
+
|
|
149
|
+
export const RpcEvent = Object.freeze({
|
|
150
|
+
State: "state",
|
|
151
|
+
} as const);
|
|
152
|
+
export type RpcEvent = ValueOf<typeof RpcEvent>;
|
|
153
|
+
|
|
154
|
+
export const OwnerKind = Object.freeze({
|
|
155
|
+
Host: "host",
|
|
156
|
+
Orb: "orb",
|
|
157
|
+
Object: "object",
|
|
158
|
+
} as const);
|
|
159
|
+
export type OwnerKind = ValueOf<typeof OwnerKind>;
|
|
160
|
+
|
|
161
|
+
export const EnvironmentPhase = Object.freeze({
|
|
162
|
+
Declaring: "declaring",
|
|
163
|
+
Prepared: "prepared",
|
|
164
|
+
Live: "live",
|
|
165
|
+
Closed: "closed",
|
|
166
|
+
} as const);
|
|
167
|
+
export type EnvironmentPhase = ValueOf<typeof EnvironmentPhase>;
|
|
168
|
+
|
|
169
|
+
export const CoordinationDecision = Object.freeze({
|
|
170
|
+
Preparing: "preparing",
|
|
171
|
+
Commit: "commit",
|
|
172
|
+
Abort: "abort",
|
|
173
|
+
} as const);
|
|
174
|
+
export type CoordinationDecision = ValueOf<typeof CoordinationDecision>;
|
|
175
|
+
|
|
176
|
+
export const Outcome = Object.freeze({
|
|
177
|
+
Ok: "ok",
|
|
178
|
+
Error: "error",
|
|
179
|
+
} as const);
|
|
180
|
+
export type Outcome = ValueOf<typeof Outcome>;
|
|
181
|
+
|
|
182
|
+
export const CodecTag = Object.freeze({
|
|
183
|
+
Bigint: "bigint",
|
|
184
|
+
Bytes: "bytes",
|
|
185
|
+
Object: "object",
|
|
186
|
+
} as const);
|
|
187
|
+
export type CodecTag = ValueOf<typeof CodecTag>;
|
|
188
|
+
|
|
189
|
+
export const CodecId = Object.freeze({
|
|
190
|
+
Json: "tembra-json/1",
|
|
191
|
+
MessagePack: "tembra-msgpack/1",
|
|
192
|
+
} as const);
|
|
193
|
+
export type CodecId = ValueOf<typeof CodecId>;
|
package/src/browser.ts
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { orb } from "./authoring/orb.ts";
|
|
2
|
+
import type { HostOptions } from "./authoring/types.ts";
|
|
3
|
+
import type { KernelPort } from "./bridge/kernel.ts";
|
|
4
|
+
import { Host } from "./host.ts";
|
|
5
|
+
|
|
6
|
+
export interface WasmModule {
|
|
7
|
+
WasmKernel: new () => KernelPort;
|
|
8
|
+
default?: (input?: unknown) => Promise<unknown>;
|
|
9
|
+
}
|
|
10
|
+
export type BrowserHostOptions = Omit<HostOptions, "kernel"> & {
|
|
11
|
+
kernel?: KernelPort;
|
|
12
|
+
wasm?: WasmModule | (() => Promise<WasmModule>);
|
|
13
|
+
wasmInput?: unknown;
|
|
14
|
+
baseURL?: string | URL;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/** Runs orbs in the browser or Worker's existing JS realm; WASM owns only kernel metadata. */
|
|
18
|
+
export async function createHost(options: BrowserHostOptions = {}): Promise<Host> {
|
|
19
|
+
let kernel = options.kernel;
|
|
20
|
+
if (!kernel) {
|
|
21
|
+
const supplied = options.wasm;
|
|
22
|
+
const module =
|
|
23
|
+
typeof supplied === "function"
|
|
24
|
+
? await supplied()
|
|
25
|
+
: (supplied ?? ((await import("@syntropika/tembra-engine-wasm")) as WasmModule));
|
|
26
|
+
await module.default?.(options.wasmInput);
|
|
27
|
+
kernel = new module.WasmKernel();
|
|
28
|
+
}
|
|
29
|
+
return new Host({
|
|
30
|
+
...options,
|
|
31
|
+
kernel,
|
|
32
|
+
load:
|
|
33
|
+
options.load ??
|
|
34
|
+
(async (location) => {
|
|
35
|
+
const base = options.baseURL ?? globalThis.location?.href;
|
|
36
|
+
const url =
|
|
37
|
+
location instanceof URL ? location : base ? new URL(location, base) : new URL(location);
|
|
38
|
+
return orb(
|
|
39
|
+
(await import(url.href)).default as import("./authoring/types.ts").OrbDefinition,
|
|
40
|
+
);
|
|
41
|
+
}),
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export { orb };
|
|
46
|
+
export type { Host };
|
|
47
|
+
|
|
48
|
+
export {
|
|
49
|
+
Code,
|
|
50
|
+
HookCapability,
|
|
51
|
+
Lifetime,
|
|
52
|
+
Reason,
|
|
53
|
+
ReloadStatus,
|
|
54
|
+
Status,
|
|
55
|
+
} from "./bridge/identifiers.ts";
|
|
56
|
+
|
|
57
|
+
export { Errors, type ErrorDescriptor } from "./errors.ts";
|
|
58
|
+
|
|
59
|
+
export { ContextKey, ContextKind, opaqueFrom, type OpaqueContextValue } from "./context-key.ts";
|
package/src/codec.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./codecs/json.ts";
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
import { CodecId, CodecTag } from "../bridge/protocol.ts";
|
|
2
|
+
import { Errors } from "../errors.ts";
|
|
3
|
+
|
|
4
|
+
import { refuse } from "../error.ts";
|
|
5
|
+
|
|
6
|
+
/** Selected once by infrastructure. Local calls and local state reads do not use a codec. */
|
|
7
|
+
export interface Codec {
|
|
8
|
+
readonly id: string;
|
|
9
|
+
/** Encode a portable value using the host's wire contract. */
|
|
10
|
+
serialize(value: unknown): Uint8Array;
|
|
11
|
+
/** Decode bytes using the same wire contract. */
|
|
12
|
+
deserialize(bytes: Uint8Array): unknown;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
const marker = "$tembra";
|
|
16
|
+
|
|
17
|
+
/** Replace non-JSON scalars with explicit tagged values. */
|
|
18
|
+
function pack(value: unknown, visiting: WeakSet<object>): unknown {
|
|
19
|
+
if (typeof value === "bigint") return { [marker]: [CodecTag.Bigint, value.toString()] };
|
|
20
|
+
if (value instanceof Uint8Array) return { [marker]: [CodecTag.Bytes, [...value]] };
|
|
21
|
+
if (value === null || typeof value === "string" || typeof value === "boolean") return value;
|
|
22
|
+
if (typeof value === "number") {
|
|
23
|
+
if (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value)))
|
|
24
|
+
refuse(Errors.Invalid.JsonNumber, "Use BigInt for integers outside the safe Number range");
|
|
25
|
+
return value;
|
|
26
|
+
}
|
|
27
|
+
if (typeof value !== "object")
|
|
28
|
+
refuse(Errors.Invalid.JsonValue, "This JSON codec requires explicit portable values");
|
|
29
|
+
if (visiting.has(value)) refuse(Errors.Invalid.JsonCycle);
|
|
30
|
+
const prototype = Object.getPrototypeOf(value);
|
|
31
|
+
if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
|
|
32
|
+
refuse(Errors.Invalid.JsonType, "Supply a codec for custom object types");
|
|
33
|
+
visiting.add(value);
|
|
34
|
+
try {
|
|
35
|
+
if (Array.isArray(value)) return Array.from(value, (child) => pack(child, visiting));
|
|
36
|
+
const entries = Reflect.ownKeys(value).map((key) => {
|
|
37
|
+
if (typeof key !== "string") refuse(Errors.Invalid.JsonSymbol);
|
|
38
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
|
|
39
|
+
if (!Object.hasOwn(descriptor, "value")) refuse(Errors.Invalid.JsonAccessor);
|
|
40
|
+
return [key, pack(descriptor.value, visiting)];
|
|
41
|
+
});
|
|
42
|
+
return Object.hasOwn(value, marker)
|
|
43
|
+
? { [marker]: [CodecTag.Object, entries] }
|
|
44
|
+
: Object.fromEntries(entries);
|
|
45
|
+
} finally {
|
|
46
|
+
visiting.delete(value);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** Restore tagged values without losing integer precision. */
|
|
51
|
+
function unpack(value: unknown): unknown {
|
|
52
|
+
if (value === null || typeof value !== "object") {
|
|
53
|
+
if (typeof value === "number" && Number.isInteger(value) && !Number.isSafeInteger(value))
|
|
54
|
+
refuse(Errors.Invalid.JsonNumber);
|
|
55
|
+
return value;
|
|
56
|
+
}
|
|
57
|
+
if (Array.isArray(value)) return value.map(unpack);
|
|
58
|
+
if (Object.hasOwn(value, marker)) {
|
|
59
|
+
const tag = (value as Record<string, unknown>)[marker];
|
|
60
|
+
if (Object.keys(value).length !== 1 || !Array.isArray(tag) || tag.length !== 2)
|
|
61
|
+
refuse(Errors.Invalid.JsonTag);
|
|
62
|
+
const [type, data] = tag;
|
|
63
|
+
if (type === CodecTag.Bigint && typeof data === "string" && /^-?(0|[1-9]\d*)$/.test(data))
|
|
64
|
+
return BigInt(data);
|
|
65
|
+
if (
|
|
66
|
+
type === CodecTag.Bytes &&
|
|
67
|
+
Array.isArray(data) &&
|
|
68
|
+
data.every((v) => Number.isInteger(v) && v >= 0 && v <= 255)
|
|
69
|
+
)
|
|
70
|
+
return Uint8Array.from(data);
|
|
71
|
+
if (type === CodecTag.Object && Array.isArray(data)) {
|
|
72
|
+
if (
|
|
73
|
+
!data.every(
|
|
74
|
+
(entry) => Array.isArray(entry) && entry.length === 2 && typeof entry[0] === "string",
|
|
75
|
+
)
|
|
76
|
+
)
|
|
77
|
+
refuse(Errors.Invalid.JsonTag);
|
|
78
|
+
return Object.fromEntries(data.map(([key, child]) => [key, unpack(child)]));
|
|
79
|
+
}
|
|
80
|
+
refuse(Errors.Invalid.JsonTag, "Unknown or malformed portable type tag");
|
|
81
|
+
}
|
|
82
|
+
return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, unpack(child)]));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Also works in a minimal embedded runtime without Web APIs. */
|
|
86
|
+
export function utf8(text: string): Uint8Array {
|
|
87
|
+
const output: number[] = [];
|
|
88
|
+
for (const character of text) {
|
|
89
|
+
let point = character.codePointAt(0)!;
|
|
90
|
+
if (point >= 0xd800 && point <= 0xdfff) point = 0xfffd;
|
|
91
|
+
if (point < 0x80) output.push(point);
|
|
92
|
+
else if (point < 0x800) output.push(0xc0 | (point >> 6), 0x80 | (point & 63));
|
|
93
|
+
else if (point < 0x10000)
|
|
94
|
+
output.push(0xe0 | (point >> 12), 0x80 | ((point >> 6) & 63), 0x80 | (point & 63));
|
|
95
|
+
else
|
|
96
|
+
output.push(
|
|
97
|
+
0xf0 | (point >> 18),
|
|
98
|
+
0x80 | ((point >> 12) & 63),
|
|
99
|
+
0x80 | ((point >> 6) & 63),
|
|
100
|
+
0x80 | (point & 63),
|
|
101
|
+
);
|
|
102
|
+
}
|
|
103
|
+
return Uint8Array.from(output);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Decode UTF-8 bytes into a string. */
|
|
107
|
+
export function text(bytes: Uint8Array): string {
|
|
108
|
+
const output: string[] = [];
|
|
109
|
+
for (let index = 0; index < bytes.length;) {
|
|
110
|
+
const first = bytes[index++]!;
|
|
111
|
+
if (first < 0x80) {
|
|
112
|
+
output.push(String.fromCharCode(first));
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
const count =
|
|
116
|
+
first >= 0xc2 && first <= 0xdf
|
|
117
|
+
? 1
|
|
118
|
+
: first >= 0xe0 && first <= 0xef
|
|
119
|
+
? 2
|
|
120
|
+
: first >= 0xf0 && first <= 0xf4
|
|
121
|
+
? 3
|
|
122
|
+
: -1;
|
|
123
|
+
if (count < 0 || index + count > bytes.length) refuse(Errors.Invalid.Utf8);
|
|
124
|
+
let point = first & (0x7f >> (count + 1));
|
|
125
|
+
for (let offset = 0; offset < count; offset++) {
|
|
126
|
+
const next = bytes[index++]!;
|
|
127
|
+
if ((next & 0xc0) !== 0x80) refuse(Errors.Invalid.Utf8);
|
|
128
|
+
point = (point << 6) | (next & 63);
|
|
129
|
+
}
|
|
130
|
+
if (
|
|
131
|
+
point < [0, 0x80, 0x800, 0x10000][count]! ||
|
|
132
|
+
point > 0x10ffff ||
|
|
133
|
+
(point >= 0xd800 && point <= 0xdfff)
|
|
134
|
+
)
|
|
135
|
+
refuse(Errors.Invalid.Utf8);
|
|
136
|
+
output.push(String.fromCodePoint(point));
|
|
137
|
+
}
|
|
138
|
+
return output.join("");
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
export const jsonCodec: Codec = Object.freeze({
|
|
142
|
+
id: CodecId.Json,
|
|
143
|
+
/** Encode supported portable scalars without losing integer precision. */
|
|
144
|
+
serialize: (value: unknown) => utf8(JSON.stringify(pack(value, new WeakSet()))),
|
|
145
|
+
/** Restore explicit portable tags from strict UTF-8 JSON. */
|
|
146
|
+
deserialize: (bytes: Uint8Array) => unpack(JSON.parse(text(bytes))),
|
|
147
|
+
});
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { decode, encode, ExtensionCodec } from "@msgpack/msgpack";
|
|
2
|
+
import { CodecId } from "../bridge/protocol.ts";
|
|
3
|
+
import type { Codec } from "./json.ts";
|
|
4
|
+
import { text, utf8 } from "./json.ts";
|
|
5
|
+
|
|
6
|
+
const extensions = new ExtensionCodec();
|
|
7
|
+
extensions.register({
|
|
8
|
+
type: 1,
|
|
9
|
+
/** Encode arbitrary-size integers as decimal UTF-8 text. */
|
|
10
|
+
encode(value) {
|
|
11
|
+
return typeof value === "bigint" ? utf8(value.toString()) : null;
|
|
12
|
+
},
|
|
13
|
+
/** Restore a BigInt without passing through a floating-point number. */
|
|
14
|
+
decode(bytes) {
|
|
15
|
+
return BigInt(text(bytes));
|
|
16
|
+
},
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
/** Numbers remain Numbers; extension 1 preserves arbitrary BigInts independently of integer size. */
|
|
20
|
+
export const messagePackCodec: Codec = Object.freeze({
|
|
21
|
+
id: CodecId.MessagePack,
|
|
22
|
+
/** Encode portable data with the shared BigInt extension. */
|
|
23
|
+
serialize: (value: unknown) => encode(value, { extensionCodec: extensions }),
|
|
24
|
+
/** Restore portable data with the matching extension codec. */
|
|
25
|
+
deserialize: (bytes: Uint8Array) => decode(bytes, { extensionCodec: extensions }),
|
|
26
|
+
});
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/** Stable scalar keys shared across bundles and languages. */
|
|
2
|
+
import type { Context } from "./runtime/context.ts";
|
|
3
|
+
import { KernelOp } from "./bridge/protocol.ts";
|
|
4
|
+
|
|
5
|
+
export const ContextKind = Object.freeze({
|
|
6
|
+
Text: "text",
|
|
7
|
+
Integer: "integer",
|
|
8
|
+
Boolean: "boolean",
|
|
9
|
+
Opaque: "opaque",
|
|
10
|
+
} as const);
|
|
11
|
+
export type ContextKind = (typeof ContextKind)[keyof typeof ContextKind];
|
|
12
|
+
/** An owner-issued reference. Its token does not retain the source frame. */
|
|
13
|
+
export interface OpaqueContextValue {
|
|
14
|
+
readonly opaque: true;
|
|
15
|
+
}
|
|
16
|
+
export class ContextKey<T> {
|
|
17
|
+
declare private readonly type: T;
|
|
18
|
+
|
|
19
|
+
/** Retain a frozen key contract; Rust validates its use. */
|
|
20
|
+
private constructor(
|
|
21
|
+
readonly name: string,
|
|
22
|
+
readonly version: number,
|
|
23
|
+
readonly kind: ContextKind,
|
|
24
|
+
) {
|
|
25
|
+
Object.freeze(this);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Declare a text binding with stable identity. */
|
|
29
|
+
static text(name: string, version = 1) {
|
|
30
|
+
return new ContextKey<string>(name, version, ContextKind.Text);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** Declare an integer binding with stable identity. */
|
|
34
|
+
static integer(name: string, version = 1) {
|
|
35
|
+
return new ContextKey<number>(name, version, ContextKind.Integer);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** Declare a boolean binding with stable identity. */
|
|
39
|
+
static boolean(name: string, version = 1) {
|
|
40
|
+
return new ContextKey<boolean>(name, version, ContextKind.Boolean);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Declare an opaque binding with stable identity. */
|
|
44
|
+
static opaque(name: string, version = 1) {
|
|
45
|
+
return new ContextKey<OpaqueContextValue>(name, version, ContextKind.Opaque);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Resolve a token issued by the owner in this host and root. */
|
|
49
|
+
source(value: T, ctx: Context): number | undefined {
|
|
50
|
+
if (this.kind !== ContextKind.Opaque) return undefined;
|
|
51
|
+
const token =
|
|
52
|
+
typeof value === "object" && value !== null
|
|
53
|
+
? ctx.session.contextTokens.get(value)
|
|
54
|
+
: undefined;
|
|
55
|
+
if (!token || token.root !== ctx.root)
|
|
56
|
+
throw new TypeError("An owner-issued opaque reference from this host and root is required");
|
|
57
|
+
return token.source;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Read metadata or wrap an owner-issued local reference. */
|
|
62
|
+
export function readContextValue<T>(
|
|
63
|
+
ctx: Context,
|
|
64
|
+
key: ContextKey<T>,
|
|
65
|
+
frame: number,
|
|
66
|
+
): T | undefined {
|
|
67
|
+
const entry = ctx.session.kernel.command<{
|
|
68
|
+
kind: ContextKind;
|
|
69
|
+
value?: T;
|
|
70
|
+
source?: number;
|
|
71
|
+
} | null>(KernelOp.ContextValue, {
|
|
72
|
+
root: ctx.root,
|
|
73
|
+
context: frame,
|
|
74
|
+
call: ctx.invocation?.id,
|
|
75
|
+
key,
|
|
76
|
+
});
|
|
77
|
+
if (!entry) return undefined;
|
|
78
|
+
if (entry.kind !== ContextKind.Opaque) return entry.value;
|
|
79
|
+
const token = Object.freeze({ opaque: true as const });
|
|
80
|
+
ctx.session.contextTokens.set(token, { root: ctx.root, source: entry.source! });
|
|
81
|
+
// SAFETY: Rust matched the opaque binding to the supplied typed key.
|
|
82
|
+
return token as T;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Read an owner-issued reference from a live source frame. */
|
|
86
|
+
export function opaqueFrom(
|
|
87
|
+
ctx: Context,
|
|
88
|
+
key: ContextKey<OpaqueContextValue>,
|
|
89
|
+
issuedFrame: number,
|
|
90
|
+
): OpaqueContextValue {
|
|
91
|
+
const token = readContextValue(ctx, key, issuedFrame);
|
|
92
|
+
if (!token) throw new TypeError("The owner did not issue a reference");
|
|
93
|
+
return token;
|
|
94
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./infrastructure/coordinator.ts";
|