@syntropika/tembra-sdk 0.0.0-stage → 0.2.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 +48 -0
- package/dist/authoring/hooks.d.ts +11 -0
- package/dist/authoring/orb.d.ts +3 -0
- package/dist/authoring/service-identities.d.ts +7 -0
- package/dist/authoring/services.d.ts +8 -0
- package/dist/authoring/types.d.ts +181 -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 +3335 -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 +98 -0
- package/dist/host.js +3278 -0
- package/dist/identifiers.d.ts +1 -0
- package/dist/index.d.ts +12 -0
- package/dist/index.js +864 -0
- package/dist/infrastructure/coordinator.d.ts +13 -0
- package/dist/infrastructure/manager.d.ts +23 -0
- package/dist/infrastructure/rpc/channel.d.ts +55 -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 +3336 -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 +1091 -0
- package/dist/runtime/activities.d.ts +30 -0
- package/dist/runtime/calls.d.ts +22 -0
- package/dist/runtime/context.d.ts +38 -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 +237 -0
- package/src/authoring/hooks.ts +101 -0
- package/src/authoring/orb.ts +88 -0
- package/src/authoring/service-identities.ts +20 -0
- package/src/authoring/services.ts +46 -0
- package/src/authoring/types.ts +256 -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 +173 -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 +107 -0
- package/src/infrastructure/rpc/client.ts +216 -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 +128 -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 +406 -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,101 @@
|
|
|
1
|
+
import { HookCapability } from "../bridge/identifiers.ts";
|
|
2
|
+
import { TembraError } from "../error.ts";
|
|
3
|
+
import { Errors } from "../errors.ts";
|
|
4
|
+
import type { HookDefinition } from "./types.ts";
|
|
5
|
+
|
|
6
|
+
/** Run participants in order with the same input. */
|
|
7
|
+
export function series(): HookDefinition {
|
|
8
|
+
return {
|
|
9
|
+
capabilities: [HookCapability.Observe],
|
|
10
|
+
/** Await each participant before starting the next. */
|
|
11
|
+
async run(ctx, input, participants) {
|
|
12
|
+
for (const participant of participants) await participant(ctx, input);
|
|
13
|
+
},
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** Pass each result to the next participant. */
|
|
18
|
+
export function waterfall(): HookDefinition {
|
|
19
|
+
return {
|
|
20
|
+
capabilities: [HookCapability.Transform],
|
|
21
|
+
/** Feed each result into the next participant. */
|
|
22
|
+
async run(ctx, value, participants) {
|
|
23
|
+
for (const participant of participants) value = await participant(ctx, value);
|
|
24
|
+
return value;
|
|
25
|
+
},
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** Return the first result that is not undefined. */
|
|
30
|
+
export function bail(): HookDefinition {
|
|
31
|
+
return {
|
|
32
|
+
capabilities: [HookCapability.Decide],
|
|
33
|
+
/** Stop at the first defined result. */
|
|
34
|
+
async run(ctx, value, participants) {
|
|
35
|
+
for (const participant of participants) {
|
|
36
|
+
const result = await participant(ctx, value);
|
|
37
|
+
if (result !== undefined) return result;
|
|
38
|
+
}
|
|
39
|
+
},
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Wait for all participants before returning or failing. */
|
|
44
|
+
export function parallel(): HookDefinition {
|
|
45
|
+
return {
|
|
46
|
+
capabilities: [HookCapability.Observe],
|
|
47
|
+
/** Wait for every participant, including those still running after failure. */
|
|
48
|
+
async run(ctx, value, participants) {
|
|
49
|
+
const settled = await Promise.allSettled(
|
|
50
|
+
participants.map((participant) => participant(ctx, value)),
|
|
51
|
+
);
|
|
52
|
+
const error = settled.find((result) => result.status === "rejected");
|
|
53
|
+
if (error?.status === "rejected") throw error.reason;
|
|
54
|
+
return settled.map((result) => (result.status === "fulfilled" ? result.value : undefined));
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Compose participants with single-use continuations. */
|
|
60
|
+
export function middleware(
|
|
61
|
+
terminal: (context: import("../runtime/context.ts").Context, input: any) => unknown,
|
|
62
|
+
): HookDefinition {
|
|
63
|
+
return {
|
|
64
|
+
capabilities: [HookCapability.Transform, HookCapability.Decide],
|
|
65
|
+
/** Keep continuations valid only while this hook run remains active. */
|
|
66
|
+
async run(ctx, input, participants) {
|
|
67
|
+
let active = true;
|
|
68
|
+
/** Keep each continuation inside its participant's physical lifetime. */
|
|
69
|
+
async function invoke(index: number, value: unknown): Promise<unknown> {
|
|
70
|
+
if (!active) throw new TembraError(Errors.Expired.Next, "Continuation scope has ended");
|
|
71
|
+
ctx.check();
|
|
72
|
+
const participant = participants[index];
|
|
73
|
+
if (!participant) return terminal(ctx, value);
|
|
74
|
+
let used = false;
|
|
75
|
+
let pending: Promise<unknown> | undefined;
|
|
76
|
+
let open = true;
|
|
77
|
+
const next = (nextValue: unknown) => {
|
|
78
|
+
if (!open || !active) return Promise.reject(new TembraError(Errors.Expired.Next));
|
|
79
|
+
if (used) return Promise.reject(new TembraError(Errors.Invalid.NextUsed));
|
|
80
|
+
used = true;
|
|
81
|
+
pending = invoke(index + 1, nextValue);
|
|
82
|
+
// A caller may catch the rejection normally; no special recovery operation exists.
|
|
83
|
+
pending.catch(() => {});
|
|
84
|
+
return pending;
|
|
85
|
+
};
|
|
86
|
+
try {
|
|
87
|
+
return await participant(ctx, value, next);
|
|
88
|
+
} finally {
|
|
89
|
+
open = false;
|
|
90
|
+
// A detached continuation still owns physical work until it settles.
|
|
91
|
+
if (pending) await pending.catch(() => {});
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
try {
|
|
95
|
+
return await invoke(0, input);
|
|
96
|
+
} finally {
|
|
97
|
+
active = false;
|
|
98
|
+
}
|
|
99
|
+
},
|
|
100
|
+
};
|
|
101
|
+
}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { Errors } from "../errors.ts";
|
|
2
|
+
|
|
3
|
+
import { refuse } from "../error.ts";
|
|
4
|
+
import { associateServices } from "./services.ts";
|
|
5
|
+
import type { OrbDefinition, ServiceDefinition } from "./types.ts";
|
|
6
|
+
|
|
7
|
+
/** Captures executable declarations. No structural schemas or generated contracts are required. */
|
|
8
|
+
export function orb<const F extends OrbDefinition>(definition: F): Readonly<F> {
|
|
9
|
+
if (!definition.name || !Number.isInteger(definition.apiVersion) || definition.apiVersion <= 0)
|
|
10
|
+
refuse(Errors.Invalid.Orb, "An orb needs a name and positive API version");
|
|
11
|
+
const services = Object.fromEntries(
|
|
12
|
+
Object.entries(definition.services ?? {}).map(([name, service]) => {
|
|
13
|
+
if (!name || !service.methods || typeof service.methods !== "object")
|
|
14
|
+
refuse(Errors.Invalid.Service);
|
|
15
|
+
if (service.create && typeof service.create !== "function") refuse(Errors.Invalid.Factory);
|
|
16
|
+
for (const handler of Object.values(service.methods)) {
|
|
17
|
+
if (typeof handler !== "function")
|
|
18
|
+
refuse(Errors.Invalid.Method, "Methods must be functions");
|
|
19
|
+
}
|
|
20
|
+
const copy: ServiceDefinition = {
|
|
21
|
+
...service,
|
|
22
|
+
methods: Object.freeze({ ...service.methods }),
|
|
23
|
+
};
|
|
24
|
+
return [name, Object.freeze(copy)];
|
|
25
|
+
}),
|
|
26
|
+
);
|
|
27
|
+
const requires = Object.fromEntries(
|
|
28
|
+
Object.entries(definition.requires ?? {}).map(([name, requirement]) => [
|
|
29
|
+
name,
|
|
30
|
+
Object.freeze({
|
|
31
|
+
...requirement,
|
|
32
|
+
...(requirement.methods ? { methods: Object.freeze([...requirement.methods]) } : {}),
|
|
33
|
+
...(requirement.hooks ? { hooks: Object.freeze([...requirement.hooks]) } : {}),
|
|
34
|
+
...(requirement.services
|
|
35
|
+
? {
|
|
36
|
+
services: Object.freeze(
|
|
37
|
+
Object.fromEntries(
|
|
38
|
+
Object.entries(requirement.services).map(([name, methods]) => [
|
|
39
|
+
name,
|
|
40
|
+
Object.freeze([...methods]),
|
|
41
|
+
]),
|
|
42
|
+
),
|
|
43
|
+
),
|
|
44
|
+
}
|
|
45
|
+
: {}),
|
|
46
|
+
}),
|
|
47
|
+
]),
|
|
48
|
+
);
|
|
49
|
+
const hooks = Object.fromEntries(
|
|
50
|
+
Object.entries(definition.hooks ?? {}).map(([name, hook]) => {
|
|
51
|
+
if (typeof hook.run !== "function") refuse(Errors.Invalid.Hook, "Hooks need a run function");
|
|
52
|
+
return [
|
|
53
|
+
name,
|
|
54
|
+
Object.freeze({ ...hook, capabilities: Object.freeze([...(hook.capabilities ?? [])]) }),
|
|
55
|
+
];
|
|
56
|
+
}),
|
|
57
|
+
);
|
|
58
|
+
const contributes = Object.fromEntries(
|
|
59
|
+
Object.entries(definition.contributes ?? {}).map(([alias, hooks]) => [
|
|
60
|
+
alias,
|
|
61
|
+
Object.freeze(
|
|
62
|
+
Object.fromEntries(
|
|
63
|
+
Object.entries(hooks).map(([name, contribution]) => [
|
|
64
|
+
name,
|
|
65
|
+
typeof contribution === "function" ? contribution : Object.freeze({ ...contribution }),
|
|
66
|
+
]),
|
|
67
|
+
),
|
|
68
|
+
),
|
|
69
|
+
]),
|
|
70
|
+
);
|
|
71
|
+
const captured = Object.freeze({
|
|
72
|
+
...definition,
|
|
73
|
+
services: Object.freeze(services),
|
|
74
|
+
requires: Object.freeze(requires),
|
|
75
|
+
hooks: Object.freeze(hooks),
|
|
76
|
+
contributes: Object.freeze(contributes),
|
|
77
|
+
});
|
|
78
|
+
associateServices(
|
|
79
|
+
definition.name,
|
|
80
|
+
definition.apiVersion,
|
|
81
|
+
Object.entries(definition.services ?? {}).map(([name, original]) => [
|
|
82
|
+
name,
|
|
83
|
+
original,
|
|
84
|
+
services[name]!,
|
|
85
|
+
]),
|
|
86
|
+
);
|
|
87
|
+
return captured as Readonly<F>;
|
|
88
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { ServiceDefinition } from "./types.ts";
|
|
2
|
+
|
|
3
|
+
export interface ServiceIdentity {
|
|
4
|
+
readonly orb: string;
|
|
5
|
+
readonly name: string;
|
|
6
|
+
readonly apiVersion: number;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
// Standalone orb bundles and public SDK entrypoints share metadata within one JavaScript realm.
|
|
10
|
+
// Weak keys retain neither removed implementations nor an additional object lifecycle.
|
|
11
|
+
const identityKey = Symbol.for("@syntropika/tembra-sdk/service-identities");
|
|
12
|
+
const existing: unknown = Object.getOwnPropertyDescriptor(globalThis, identityKey)?.value;
|
|
13
|
+
if (existing !== undefined && !(existing instanceof WeakMap))
|
|
14
|
+
throw new TypeError("The SDK service identity slot must contain a WeakMap");
|
|
15
|
+
|
|
16
|
+
export const serviceIdentities: WeakMap<ServiceDefinition, ServiceIdentity> =
|
|
17
|
+
existing instanceof WeakMap ? existing : new WeakMap();
|
|
18
|
+
|
|
19
|
+
if (existing === undefined)
|
|
20
|
+
Object.defineProperty(globalThis, identityKey, { value: serviceIdentities });
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { refuse } from "../error.ts";
|
|
2
|
+
import { Errors } from "../errors.ts";
|
|
3
|
+
import { serviceIdentities, type ServiceIdentity } from "./service-identities.ts";
|
|
4
|
+
import type { AcquisitionOptions, ServiceDefinition } from "./types.ts";
|
|
5
|
+
|
|
6
|
+
/** Associate original and captured services only after the whole orb declaration succeeds. */
|
|
7
|
+
export function associateServices(
|
|
8
|
+
orb: string,
|
|
9
|
+
apiVersion: number,
|
|
10
|
+
services: readonly (readonly [string, ServiceDefinition, ServiceDefinition])[],
|
|
11
|
+
): void {
|
|
12
|
+
const pending = new Map<ServiceDefinition, ServiceIdentity>();
|
|
13
|
+
for (const [name, original, captured] of services) {
|
|
14
|
+
const identity = { orb, name, apiVersion };
|
|
15
|
+
for (const definition of [original, captured]) {
|
|
16
|
+
const previous = pending.get(definition) ?? serviceIdentities.get(definition);
|
|
17
|
+
if (
|
|
18
|
+
previous &&
|
|
19
|
+
(previous.orb !== orb || previous.name !== name || previous.apiVersion !== apiVersion)
|
|
20
|
+
)
|
|
21
|
+
refuse(
|
|
22
|
+
Errors.Invalid.Service,
|
|
23
|
+
"A service definition must have one orb, name and API version",
|
|
24
|
+
);
|
|
25
|
+
pending.set(definition, identity);
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
for (const [definition, identity] of pending) serviceIdentities.set(definition, identity);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Resolve a declared service without changing the kernel's named acquisition or authority rules. */
|
|
32
|
+
export function serviceAcquisition(
|
|
33
|
+
service: string | ServiceDefinition,
|
|
34
|
+
options: AcquisitionOptions = {},
|
|
35
|
+
): { name: string; options: AcquisitionOptions } {
|
|
36
|
+
if (typeof service === "string") return { name: service, options };
|
|
37
|
+
const identity = serviceIdentities.get(service);
|
|
38
|
+
if (!identity)
|
|
39
|
+
refuse(Errors.Invalid.Service, "Declare this service in an orb before acquiring it");
|
|
40
|
+
if (options.apiVersion !== undefined && options.apiVersion !== identity.apiVersion)
|
|
41
|
+
refuse(
|
|
42
|
+
Errors.Invalid.Service,
|
|
43
|
+
"The acquisition API version must match the service declaration",
|
|
44
|
+
);
|
|
45
|
+
return { name: identity.name, options: { ...options, apiVersion: identity.apiVersion } };
|
|
46
|
+
}
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
import { Lifetime, ReloadStatus, Status } from "../bridge/identifiers.ts";
|
|
2
|
+
import type { Invocation, KernelOrb, KernelPort } from "../bridge/kernel.ts";
|
|
3
|
+
import type { Codec } from "../codecs/json.ts";
|
|
4
|
+
import type { Context } from "../runtime/context.ts";
|
|
5
|
+
import type { Readable, State } from "../state.ts";
|
|
6
|
+
import type { Declaration } from "./declaration.ts";
|
|
7
|
+
|
|
8
|
+
export type Completion<T> = T | PromiseLike<T>;
|
|
9
|
+
|
|
10
|
+
// Executable definitions are heterogeneous. These dynamic positions carry caller-owned types;
|
|
11
|
+
// runtime authority and ownership are established by the kernel, not TypeScript casts.
|
|
12
|
+
export type Handler = (environment: any, context: Context, ...arguments_: any[]) => unknown;
|
|
13
|
+
export interface ServiceDefinition {
|
|
14
|
+
create?: (self: Declaration) => unknown;
|
|
15
|
+
methods: Record<string, Handler>;
|
|
16
|
+
lifetime?: Lifetime;
|
|
17
|
+
|
|
18
|
+
/** Idle milliseconds to retain an unreferenced object and its running tasks; defaults to zero. */
|
|
19
|
+
linger?: number;
|
|
20
|
+
access?: (principal: string) => { methods: readonly string[] };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export interface Requirement {
|
|
24
|
+
orb?: string;
|
|
25
|
+
apiVersion: number;
|
|
26
|
+
methods?: readonly string[];
|
|
27
|
+
services?: Readonly<Record<string, readonly string[]>>;
|
|
28
|
+
hooks?: readonly string[];
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface HookDefinition {
|
|
32
|
+
capabilities?: readonly string[];
|
|
33
|
+
|
|
34
|
+
/** Execute a hook with its admitted participants. */
|
|
35
|
+
run(context: Context, input: any, participants: readonly Participant[]): Completion<unknown>;
|
|
36
|
+
}
|
|
37
|
+
export type Participant = (
|
|
38
|
+
context: Context,
|
|
39
|
+
input: any,
|
|
40
|
+
next?: (input: any) => Promise<unknown>,
|
|
41
|
+
) => Promise<any>;
|
|
42
|
+
export type ContributionHandler = (
|
|
43
|
+
context: Context,
|
|
44
|
+
input: any,
|
|
45
|
+
next?: (input: any) => Promise<unknown>,
|
|
46
|
+
) => unknown;
|
|
47
|
+
export type Contribution = ContributionHandler | { handle: ContributionHandler; priority?: number };
|
|
48
|
+
|
|
49
|
+
export interface OrbDefinition {
|
|
50
|
+
name: string;
|
|
51
|
+
apiVersion: number;
|
|
52
|
+
requires?: Readonly<Record<string, Requirement>>;
|
|
53
|
+
create?: (self: Declaration) => unknown;
|
|
54
|
+
services?: Readonly<Record<string, ServiceDefinition>>;
|
|
55
|
+
hooks?: Readonly<Record<string, HookDefinition>>;
|
|
56
|
+
contributes?: Readonly<Record<string, Readonly<Record<string, Contribution>>>>;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export interface ResourceOptions<T> {
|
|
60
|
+
version?: number;
|
|
61
|
+
exclusive?: boolean;
|
|
62
|
+
opaque?: boolean;
|
|
63
|
+
deps?: readonly unknown[];
|
|
64
|
+
|
|
65
|
+
/** Create the resource value and observe cancellation when supported. */
|
|
66
|
+
open(signal: AbortSignal): Completion<T>;
|
|
67
|
+
|
|
68
|
+
/** Release the value after its physical users settle. */
|
|
69
|
+
close?(value: T, context: Context): Completion<unknown>;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
export interface Resource<T> {
|
|
73
|
+
readonly value: T;
|
|
74
|
+
readonly version: number;
|
|
75
|
+
}
|
|
76
|
+
export interface TaskScope {
|
|
77
|
+
readonly signal: AbortSignal;
|
|
78
|
+
|
|
79
|
+
/** Run one operation under this task's authority. */
|
|
80
|
+
root<T>(operation: (context: Context) => Completion<T>): Promise<T>;
|
|
81
|
+
}
|
|
82
|
+
export interface EventSource<T> {
|
|
83
|
+
/** Attach a listener and return its detach function. */
|
|
84
|
+
subscribe(listener: (value: T) => void): () => void;
|
|
85
|
+
}
|
|
86
|
+
export interface ListenerOptions {
|
|
87
|
+
maxPending?: number;
|
|
88
|
+
maxBytes?: number;
|
|
89
|
+
sizeOf?: (value: any) => number;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
export interface ReferenceBase<T = unknown> {
|
|
93
|
+
readonly ready: Promise<void>;
|
|
94
|
+
readonly status: Status;
|
|
95
|
+
readonly state: Readable<T>;
|
|
96
|
+
|
|
97
|
+
/** Release this reference's ownership claim. */
|
|
98
|
+
release(): void;
|
|
99
|
+
|
|
100
|
+
/** Read an explicitly exposed local resource. */
|
|
101
|
+
opaque<R = unknown>(name: string): R;
|
|
102
|
+
}
|
|
103
|
+
export type DynamicReference = ReferenceBase<any> & Record<string, any>;
|
|
104
|
+
|
|
105
|
+
type EnvironmentState<Environment> = 0 extends 1 & Environment
|
|
106
|
+
? unknown
|
|
107
|
+
: Environment extends State<infer Value>
|
|
108
|
+
? Value
|
|
109
|
+
: Environment extends object
|
|
110
|
+
? {
|
|
111
|
+
[Member in keyof Environment]-?: Environment[Member] extends State<infer Value>
|
|
112
|
+
? Value
|
|
113
|
+
: never;
|
|
114
|
+
}[keyof Environment]
|
|
115
|
+
: never;
|
|
116
|
+
|
|
117
|
+
type ServiceState<Service> = Service extends { create: (...args: never[]) => infer Environment }
|
|
118
|
+
? [EnvironmentState<Environment>] extends [never]
|
|
119
|
+
? unknown
|
|
120
|
+
: EnvironmentState<Environment>
|
|
121
|
+
: unknown;
|
|
122
|
+
|
|
123
|
+
type ArgumentTail<Arguments extends unknown[]> = Arguments extends []
|
|
124
|
+
? []
|
|
125
|
+
: Arguments extends [unknown?, ...infer Rest]
|
|
126
|
+
? Rest
|
|
127
|
+
: [];
|
|
128
|
+
|
|
129
|
+
type BusinessArguments<Arguments extends unknown[]> = ArgumentTail<ArgumentTail<Arguments>>;
|
|
130
|
+
|
|
131
|
+
// An optional tuple suffix after a rest parameter would also admit Context in the middle.
|
|
132
|
+
type CallArguments<Arguments extends unknown[]> = number extends Arguments["length"]
|
|
133
|
+
? Arguments | [...Arguments, Context]
|
|
134
|
+
: [...Arguments, context?: Context];
|
|
135
|
+
|
|
136
|
+
type ConsumerMethod<Method> = Method extends (...args: infer Arguments) => infer Result
|
|
137
|
+
? (...args: CallArguments<BusinessArguments<Arguments>>) => Promise<Awaited<Result>>
|
|
138
|
+
: never;
|
|
139
|
+
|
|
140
|
+
/** A managed reference inferred from one service's methods and explicitly returned State handles. */
|
|
141
|
+
export type ServiceReference<Service extends ServiceDefinition> = ReferenceBase<
|
|
142
|
+
ServiceState<Service>
|
|
143
|
+
> & {
|
|
144
|
+
[Method in Exclude<keyof Service["methods"], keyof ReferenceBase | "then">]: ConsumerMethod<
|
|
145
|
+
Service["methods"][Method]
|
|
146
|
+
>;
|
|
147
|
+
};
|
|
148
|
+
|
|
149
|
+
export interface AcquisitionOptions {
|
|
150
|
+
apiVersion?: number;
|
|
151
|
+
methods?: readonly string[];
|
|
152
|
+
principal?: string;
|
|
153
|
+
}
|
|
154
|
+
export interface ReloadOptions {
|
|
155
|
+
deadline?: number;
|
|
156
|
+
}
|
|
157
|
+
export interface ReloadReport {
|
|
158
|
+
codeVersion: number;
|
|
159
|
+
orbs: readonly string[];
|
|
160
|
+
}
|
|
161
|
+
export interface PreparedReload {
|
|
162
|
+
readonly report: ReloadReport;
|
|
163
|
+
readonly status: ReloadStatus;
|
|
164
|
+
|
|
165
|
+
/** Adopt the prepared replacement and start its scopes. */
|
|
166
|
+
commit(): Promise<ReloadReport>;
|
|
167
|
+
|
|
168
|
+
/** Discard the candidate and restore previous scopes. */
|
|
169
|
+
abort(): Promise<void>;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
export interface NativeAdapter {
|
|
173
|
+
/** Recheck context authority and admit one call using the kernel command rules. */
|
|
174
|
+
admit?(
|
|
175
|
+
reference: number,
|
|
176
|
+
method: string,
|
|
177
|
+
context: Context,
|
|
178
|
+
): { call: Invocation; native: boolean };
|
|
179
|
+
/** Tick the supplied host clock, finish a call, then drain actions and read the deadline. */
|
|
180
|
+
finish?(
|
|
181
|
+
call: number,
|
|
182
|
+
now: number,
|
|
183
|
+
): { actions: import("../bridge/kernel.ts").Action[]; deadline: number | null };
|
|
184
|
+
/** Revoke native reference claims issued inside a JS-owned root. */
|
|
185
|
+
rootEnded?(root: number): void;
|
|
186
|
+
/** Return a native service's principal-specific method policy when configured. */
|
|
187
|
+
access?(orb: number, service: string, principal: string): readonly string[] | undefined;
|
|
188
|
+
/** Await native callbacks while this realm keeps dispatching their replies. */
|
|
189
|
+
settled?(): Promise<void>;
|
|
190
|
+
/** Mirror shared kernel notifications into native callback storage. */
|
|
191
|
+
notify?(action: import("../bridge/kernel.ts").Action): boolean;
|
|
192
|
+
|
|
193
|
+
/** Check whether Rust owns a managed hook participant. */
|
|
194
|
+
hasContribution?(operation: number): boolean;
|
|
195
|
+
|
|
196
|
+
/** Execute a native hook participant while retaining its physical lifetime. */
|
|
197
|
+
contribute?(operation: number, context: Context, input: unknown): Promise<unknown>;
|
|
198
|
+
|
|
199
|
+
/** Check whether Rust owns this orb implementation. */
|
|
200
|
+
hasOrb(id: number): boolean;
|
|
201
|
+
|
|
202
|
+
/** Declare the native object's scopes before activation. */
|
|
203
|
+
activate(
|
|
204
|
+
object: number,
|
|
205
|
+
orb: number,
|
|
206
|
+
service: string,
|
|
207
|
+
key: readonly string[],
|
|
208
|
+
principal: string,
|
|
209
|
+
): Promise<void>;
|
|
210
|
+
|
|
211
|
+
/** Execute an admitted call in Rust. */
|
|
212
|
+
invoke(
|
|
213
|
+
invocation: Invocation,
|
|
214
|
+
arguments_: readonly unknown[],
|
|
215
|
+
context: Context,
|
|
216
|
+
): Promise<unknown>;
|
|
217
|
+
|
|
218
|
+
/** Release native object storage after scope cleanup. */
|
|
219
|
+
dispose(object: number): Promise<void>;
|
|
220
|
+
|
|
221
|
+
/** Execute a language callback requested by the kernel. */
|
|
222
|
+
effect(effect: import("../bridge/kernel.ts").Effect): Promise<number | void>;
|
|
223
|
+
|
|
224
|
+
/** Signals cancellation without acknowledging physical effect completion. */
|
|
225
|
+
cancelEffect?(effect: import("../bridge/kernel.ts").Effect): Completion<void>;
|
|
226
|
+
|
|
227
|
+
/** Decode a native value for the JS adapter. */
|
|
228
|
+
value(id: number): unknown;
|
|
229
|
+
|
|
230
|
+
/** Release the native value's bridge slot. */
|
|
231
|
+
dropValue?(id: number): void;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
export interface HostOptions {
|
|
235
|
+
/** Explicit monotonic origin for adapters sharing an already-running kernel. */
|
|
236
|
+
clockOrigin?: number;
|
|
237
|
+
name?: string;
|
|
238
|
+
principal?: string;
|
|
239
|
+
kernel: KernelPort;
|
|
240
|
+
serialization?: Codec;
|
|
241
|
+
load?: (location: string | URL) => Promise<OrbDefinition>;
|
|
242
|
+
|
|
243
|
+
/** Receives adapter and observer failures; throwing from this callback cannot interrupt dispatch. */
|
|
244
|
+
onError?: (error: Error) => void;
|
|
245
|
+
|
|
246
|
+
/** Monotonic milliseconds from any origin; each host measures time relative to its creation. */
|
|
247
|
+
now?: () => number;
|
|
248
|
+
native?: NativeAdapter;
|
|
249
|
+
resources?: Readonly<Record<string, ResourceOptions<unknown>>>;
|
|
250
|
+
telemetry?: { capacity?: number; sampleEvery?: number };
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
export interface OrbDescription extends KernelOrb {
|
|
254
|
+
/** Read metadata without activating orb services. */
|
|
255
|
+
describe(): Readonly<KernelOrb>;
|
|
256
|
+
}
|