@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,30 @@
|
|
|
1
|
+
import type { Environment, ListenerRecord, TaskRecord } from "./records.ts";
|
|
2
|
+
import type { Session } from "./session.ts";
|
|
3
|
+
export declare class Activities {
|
|
4
|
+
#private;
|
|
5
|
+
readonly session: Session;
|
|
6
|
+
readonly tasks: Map<number, TaskRecord>;
|
|
7
|
+
readonly listeners: Map<number, ListenerRecord>;
|
|
8
|
+
/** Keep task and listener callbacks for this session. */
|
|
9
|
+
constructor(session: Session);
|
|
10
|
+
/** Attach declared sources using subscription identities issued by Rust. */
|
|
11
|
+
prepare(environment: Environment, previous?: Environment): void;
|
|
12
|
+
/** Start tasks and retarget listeners after scope adoption. */
|
|
13
|
+
start(environment: Environment): void;
|
|
14
|
+
/** Run one task until its physical callback settles. */
|
|
15
|
+
private startTask;
|
|
16
|
+
/** Reuse one kernel identity for the same source or sizing callback. */
|
|
17
|
+
private identity;
|
|
18
|
+
/** Execute an admitted delivery and acknowledge physical settlement. */
|
|
19
|
+
deliver(subscription: number, payload: number, operation: number): void;
|
|
20
|
+
/** Stop a listener selected by the kernel. */
|
|
21
|
+
detach(id: number): void;
|
|
22
|
+
/** Signal task cancellation without releasing its ownership. */
|
|
23
|
+
cancel(id: number): void;
|
|
24
|
+
/** Report queue exhaustion and stop its source listener. */
|
|
25
|
+
failed(id: number): void;
|
|
26
|
+
/** Detach the source and release its kernel subscription once. */
|
|
27
|
+
private stopListener;
|
|
28
|
+
/** Wait for owned tasks and admitted deliveries to settle. */
|
|
29
|
+
stop(environment: Environment): Promise<void>;
|
|
30
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { Completion } from "../authoring/types.ts";
|
|
2
|
+
import { Context } from "./context.ts";
|
|
3
|
+
import type { Environment, ReferenceRecord } from "./records.ts";
|
|
4
|
+
import type { Session } from "./session.ts";
|
|
5
|
+
/** Execute JS calls. Rust controls admission and physical lifetime. */
|
|
6
|
+
export declare class Calls {
|
|
7
|
+
readonly session: Session;
|
|
8
|
+
/** Connect JS callback execution to the session kernel. */
|
|
9
|
+
constructor(session: Session);
|
|
10
|
+
/** Lazily mirror root cancellation into an AbortSignal. */
|
|
11
|
+
signal(root: number): AbortSignal;
|
|
12
|
+
/** Revoke claims and cancellation mirrors when either language ends a root. */
|
|
13
|
+
releaseRoot(root: number): void;
|
|
14
|
+
/** Release root-owned references after the callback settles. */
|
|
15
|
+
root<T>(operation: (context: Context) => Completion<T>, cleanup?: boolean, issuedRoot?: number, principal?: string): Promise<T>;
|
|
16
|
+
/** Execute one admitted service call and retain physical ownership. */
|
|
17
|
+
invoke(reference: ReferenceRecord, method: string, arguments_: unknown[], ctx: Context): Promise<unknown>;
|
|
18
|
+
/** Fresh callback roots inherit owner identity; supplied roots retain the caller's authority. */
|
|
19
|
+
owned<T>(environment: Environment, operation: number, handle: (ctx: Context) => Completion<T>, root?: number | Context): Promise<T>;
|
|
20
|
+
/** Stop waiting on cancellation while physical work remains tracked. */
|
|
21
|
+
observe<T>(physical: Promise<T>, signal: AbortSignal): Promise<T>;
|
|
22
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import { ContextKey } from "../context-key.ts";
|
|
2
|
+
import type { AcquisitionOptions, DynamicReference } from "../authoring/types.ts";
|
|
3
|
+
import type { Invocation } from "../bridge/kernel.ts";
|
|
4
|
+
import type { Session } from "./session.ts";
|
|
5
|
+
/** An issued operation scope. Keeping this object does not extend its root or invocation. */
|
|
6
|
+
export declare class Context {
|
|
7
|
+
readonly session: Session;
|
|
8
|
+
readonly root: number;
|
|
9
|
+
readonly invocation?: Invocation | undefined;
|
|
10
|
+
readonly frame: number;
|
|
11
|
+
/** Issue a context for an existing root and optional admitted call. */
|
|
12
|
+
constructor(session: Session, root: number, invocation?: Invocation | undefined, frame?: number);
|
|
13
|
+
/** Derive one binding without changing identity or lifetime. */
|
|
14
|
+
with<T>(key: ContextKey<T>, value: T): Context;
|
|
15
|
+
/** Read the nearest binding of this typed key. */
|
|
16
|
+
value<T>(key: ContextKey<T>): T | undefined;
|
|
17
|
+
/** Export only explicitly allowed scalar metadata. */
|
|
18
|
+
exportValues(keys: readonly ContextKey<unknown>[]): Record<string, unknown>;
|
|
19
|
+
/** Read the root identity from the kernel. */
|
|
20
|
+
get principal(): string;
|
|
21
|
+
/** Read the shared cancellation signal for this root. */
|
|
22
|
+
get signal(): AbortSignal;
|
|
23
|
+
/** Reject a cancelled root or expired invocation. */
|
|
24
|
+
check(): void;
|
|
25
|
+
/** Cancel the root and dispatch its cancellation actions. */
|
|
26
|
+
cancel(): void;
|
|
27
|
+
/** Acquire a reference whose claim ends with this root. */
|
|
28
|
+
get(service: string, key: string | readonly string[], options?: AcquisitionOptions): Promise<DynamicReference>;
|
|
29
|
+
/** Read a named host resource while the context remains valid. */
|
|
30
|
+
resource<T>(name: string): import("../authoring/types.ts").Resource<T>;
|
|
31
|
+
}
|
|
32
|
+
/** Require a context issued by the same host without checking cancellation or expiry. */
|
|
33
|
+
export declare function issuedContext(value: unknown, session: Session): Context;
|
|
34
|
+
/** Require a live context issued by the same host. */
|
|
35
|
+
export declare function context(value: unknown, session: Session): Context;
|
|
36
|
+
/** Recognize an issued context without extending its lifetime. */
|
|
37
|
+
export declare function isContext(value: unknown): value is Context;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "../authoring/declaration.ts";
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { Action, Diagnostics } from "../bridge/kernel.ts";
|
|
2
|
+
import type { Session } from "./session.ts";
|
|
3
|
+
/** Dispatch core actions and wait for physical shutdown. */
|
|
4
|
+
export declare class Lifecycle {
|
|
5
|
+
#private;
|
|
6
|
+
readonly session: Session;
|
|
7
|
+
/** Connect kernel actions to JS cleanup and scheduling. */
|
|
8
|
+
constructor(session: Session);
|
|
9
|
+
/** Read final counts after kernel storage has been released. */
|
|
10
|
+
get closedDiagnostics(): ReturnType<Lifecycle["diagnostics"]> | undefined;
|
|
11
|
+
/** Drain kernel actions without re-entering the dispatcher. */
|
|
12
|
+
flush(initial?: Action[]): void;
|
|
13
|
+
/** Compose kernel finish bookkeeping through the embedded adapter when available. */
|
|
14
|
+
finishCall(call: number): void;
|
|
15
|
+
/** Execute one action using its owning JS module. */
|
|
16
|
+
private action;
|
|
17
|
+
/** Wait for object activation and cleanup before releasing its binding. */
|
|
18
|
+
private dispose;
|
|
19
|
+
/** Keep one timer for the kernel's earliest deadline. */
|
|
20
|
+
private scheduleLinger;
|
|
21
|
+
/** Combine kernel counts with retained JS values and jobs. */
|
|
22
|
+
diagnostics(): Diagnostics & {
|
|
23
|
+
values: number;
|
|
24
|
+
pendingJobs: number;
|
|
25
|
+
};
|
|
26
|
+
/** Wait for physical cleanup before releasing the platform binding. */
|
|
27
|
+
close(): Promise<void>;
|
|
28
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { ContributionHandler, OrbDefinition } from "../authoring/types.ts";
|
|
2
|
+
import { Context } from "./context.ts";
|
|
3
|
+
import type { Environment, OrbRecord } from "./records.ts";
|
|
4
|
+
import type { Session } from "./session.ts";
|
|
5
|
+
export declare class Orbs {
|
|
6
|
+
#private;
|
|
7
|
+
readonly session: Session;
|
|
8
|
+
readonly records: Map<number, OrbRecord>;
|
|
9
|
+
readonly operations: Map<number, {
|
|
10
|
+
orb: OrbRecord;
|
|
11
|
+
handler: ContributionHandler;
|
|
12
|
+
}>;
|
|
13
|
+
/** Retain local implementations and contribution callbacks. */
|
|
14
|
+
constructor(session: Session);
|
|
15
|
+
/** Capture definitions and encode their kernel-owned contracts. */
|
|
16
|
+
declarations(definitions: readonly OrbDefinition[]): {
|
|
17
|
+
definitions: OrbDefinition[];
|
|
18
|
+
metadata: unknown[];
|
|
19
|
+
};
|
|
20
|
+
/** Commit new orb metadata before opening its scopes. */
|
|
21
|
+
install(definitions: readonly OrbDefinition[]): Promise<void>;
|
|
22
|
+
/** Declare one shared scope for this orb version. */
|
|
23
|
+
scope(record: OrbRecord): Environment;
|
|
24
|
+
/** Share pending activation and clean up failed orb scopes. */
|
|
25
|
+
ready(record: OrbRecord): Promise<void>;
|
|
26
|
+
/** Register callback identities with stable contribution order. */
|
|
27
|
+
registerContributions(record: OrbRecord): void;
|
|
28
|
+
/** Validate the caller and execute the kernel's admitted hook plan. */
|
|
29
|
+
runHook(environment: Environment, name: string, context: Context, input: unknown): Promise<unknown>;
|
|
30
|
+
/** Await the kernel's single owner-bound hook observation, including after cancellation.
|
|
31
|
+
* The observation starts with an empty metadata frame. It does not revive the source context.
|
|
32
|
+
* Host/owner cleanup can cancel it; physical work remains tracked until it settles.
|
|
33
|
+
*/
|
|
34
|
+
observe(environment: Environment, name: string, operation: number, source: Context, input: unknown): Promise<void>;
|
|
35
|
+
/** Execute a participant from either adapter under its own managed orb invocation. */
|
|
36
|
+
runContribution(operation: number, ctx: Context, input: unknown, next?: (input: unknown) => Promise<unknown>): Promise<unknown>;
|
|
37
|
+
/** Clean up a retired version before removing its callbacks. */
|
|
38
|
+
retire(id: number): void;
|
|
39
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Action } from "../bridge/kernel.ts";
|
|
2
|
+
import type { Environment } from "./records.ts";
|
|
3
|
+
import type { Session } from "./session.ts";
|
|
4
|
+
/** Language effects only. The Rust program owns readiness, ordering, gates and recovery decisions. */
|
|
5
|
+
export declare class Programs {
|
|
6
|
+
#private;
|
|
7
|
+
readonly session: Session;
|
|
8
|
+
readonly scopes: Map<number, Environment>;
|
|
9
|
+
/** Retain effect scopes and pending program completions. */
|
|
10
|
+
constructor(session: Session);
|
|
11
|
+
/** Describe a declared scope to the Rust lifecycle engine. */
|
|
12
|
+
register(environment: Environment): void;
|
|
13
|
+
/** Activate an already registered scope and wait for its program. */
|
|
14
|
+
activate(scope: number): Promise<void>;
|
|
15
|
+
/** Ask the kernel to retire existing scopes and await completion. */
|
|
16
|
+
cleanup(environments: readonly Environment[]): Promise<void>;
|
|
17
|
+
/** Run cleanup for kernel-issued scope identities without resolving JS callbacks. */
|
|
18
|
+
cleanupScopes(scopes: readonly number[]): Promise<void>;
|
|
19
|
+
/** Keep both adapters informed when they await the same kernel activation. */
|
|
20
|
+
pending(program: number): boolean;
|
|
21
|
+
/** Share one completion promise for a kernel program. */
|
|
22
|
+
run(program: number): Promise<void>;
|
|
23
|
+
/** Dispatches opaque engine requests and acknowledges physical callback settlement. */
|
|
24
|
+
dispatch(action: Action): void;
|
|
25
|
+
/** Resolve a live or recently closed resource callback record. */
|
|
26
|
+
private resource;
|
|
27
|
+
/** Execute a language effect without deciding lifecycle order. */
|
|
28
|
+
private execute;
|
|
29
|
+
/** Validate and retain candidate state before later publication. */
|
|
30
|
+
private candidate;
|
|
31
|
+
}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import type { Completion, DynamicReference, EventSource, OrbDefinition, ListenerOptions, Resource, ResourceOptions, TaskScope } from "../authoring/types.ts";
|
|
2
|
+
import type { KernelOrb, Owner } from "../bridge/kernel.ts";
|
|
3
|
+
import { EnvironmentPhase } from "../bridge/protocol.ts";
|
|
4
|
+
import type { StateBinding, StateOptions } from "../state.ts";
|
|
5
|
+
import type { Context } from "./context.ts";
|
|
6
|
+
export interface OrbRecord {
|
|
7
|
+
info: KernelOrb;
|
|
8
|
+
definition: OrbDefinition;
|
|
9
|
+
scope?: Environment;
|
|
10
|
+
ticket?: number | undefined;
|
|
11
|
+
}
|
|
12
|
+
export interface Address {
|
|
13
|
+
service: string;
|
|
14
|
+
key: string[];
|
|
15
|
+
principal: string;
|
|
16
|
+
}
|
|
17
|
+
export interface ObjectRecord {
|
|
18
|
+
id: number;
|
|
19
|
+
address: Address;
|
|
20
|
+
orb: number;
|
|
21
|
+
versions: Map<number, Environment>;
|
|
22
|
+
activation: Promise<void>;
|
|
23
|
+
live?: boolean;
|
|
24
|
+
binding?: StateBinding<any>;
|
|
25
|
+
error?: unknown;
|
|
26
|
+
disposing?: Promise<void>;
|
|
27
|
+
}
|
|
28
|
+
export interface Environment {
|
|
29
|
+
id: number;
|
|
30
|
+
owner: Owner;
|
|
31
|
+
orb: OrbRecord;
|
|
32
|
+
object?: ObjectRecord;
|
|
33
|
+
phase: EnvironmentPhase;
|
|
34
|
+
value: any;
|
|
35
|
+
dependencies: Map<string, DynamicReference>;
|
|
36
|
+
resources: Map<string, ResourceRecord>;
|
|
37
|
+
resourceDeclarations?: Map<ResourceRecord, ResourceOptions<any>>;
|
|
38
|
+
tasks: TaskDefinition[];
|
|
39
|
+
listeners: ListenerDefinition[];
|
|
40
|
+
state?: {
|
|
41
|
+
initial: any;
|
|
42
|
+
options: StateOptions<any>;
|
|
43
|
+
binding: StateBinding<any>;
|
|
44
|
+
publish?: () => void;
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
export interface ResourceRecord {
|
|
48
|
+
id: number;
|
|
49
|
+
name: string;
|
|
50
|
+
options: ResourceOptions<any>;
|
|
51
|
+
handle: Resource<any>;
|
|
52
|
+
dependencies: number[];
|
|
53
|
+
/** Share one physical resource-open operation. */
|
|
54
|
+
start(): Promise<void>;
|
|
55
|
+
started?: Promise<void>;
|
|
56
|
+
controller: AbortController;
|
|
57
|
+
value?: number;
|
|
58
|
+
closed?: Promise<void>;
|
|
59
|
+
/** Rebind a restored resource to its new kernel identity. */
|
|
60
|
+
reset(id: number): void;
|
|
61
|
+
}
|
|
62
|
+
export interface TaskDefinition {
|
|
63
|
+
/** Run the task callback under its scope's cancellation signal. */
|
|
64
|
+
start(scope: TaskScope): Completion<void>;
|
|
65
|
+
running?: TaskRecord;
|
|
66
|
+
}
|
|
67
|
+
export interface TaskRecord {
|
|
68
|
+
id: number;
|
|
69
|
+
controller: AbortController;
|
|
70
|
+
done: Promise<void>;
|
|
71
|
+
}
|
|
72
|
+
export interface ListenerDefinition {
|
|
73
|
+
name: string;
|
|
74
|
+
source: EventSource<any> | (() => EventSource<any>);
|
|
75
|
+
handle: (context: Context, value: any) => unknown;
|
|
76
|
+
options: ListenerOptions;
|
|
77
|
+
running?: ListenerRecord;
|
|
78
|
+
}
|
|
79
|
+
export interface ListenerRecord {
|
|
80
|
+
id: number;
|
|
81
|
+
/** Remove the source subscription. */
|
|
82
|
+
detach(): void;
|
|
83
|
+
done?: Promise<void>;
|
|
84
|
+
definition: ListenerDefinition;
|
|
85
|
+
environment: Environment;
|
|
86
|
+
stopped: boolean;
|
|
87
|
+
}
|
|
88
|
+
export interface ReferenceRecord {
|
|
89
|
+
id: number;
|
|
90
|
+
object: number;
|
|
91
|
+
address: Address;
|
|
92
|
+
ready: Promise<void>;
|
|
93
|
+
methods: Set<string>;
|
|
94
|
+
requiredMethods: ReadonlySet<string>;
|
|
95
|
+
stateCleanups: Set<() => void>;
|
|
96
|
+
nativeOwned?: boolean;
|
|
97
|
+
context?: Context;
|
|
98
|
+
released: boolean;
|
|
99
|
+
}
|
|
100
|
+
/** Create a promise with explicit completion functions. */
|
|
101
|
+
export declare function deferred<T>(): {
|
|
102
|
+
promise: Promise<T>;
|
|
103
|
+
/** Settle the shared completion with its result. */
|
|
104
|
+
resolve(value: T): void;
|
|
105
|
+
/** Reject the shared completion without an unhandled rejection. */
|
|
106
|
+
reject(error: unknown): void;
|
|
107
|
+
};
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import type { AcquisitionOptions, DynamicReference } from "../authoring/types.ts";
|
|
2
|
+
import type { Acquisition } from "../bridge/kernel.ts";
|
|
3
|
+
import { Context } from "./context.ts";
|
|
4
|
+
import type { Address, OrbRecord, ObjectRecord, ReferenceRecord } from "./records.ts";
|
|
5
|
+
import type { Session } from "./session.ts";
|
|
6
|
+
/** JS reference handles and per-object visibility. */
|
|
7
|
+
export declare class References {
|
|
8
|
+
#private;
|
|
9
|
+
readonly session: Session;
|
|
10
|
+
/** Retain handle metadata and index references by object. */
|
|
11
|
+
constructor(session: Session);
|
|
12
|
+
/** Activate an object reserved by the native facade in this shared kernel. */
|
|
13
|
+
activateAcquired(acquired: Acquisition, address: Address, requiredMethods?: string[]): Promise<void>;
|
|
14
|
+
/** Acquire ownership and create a local service handle. */
|
|
15
|
+
hold(service: string, key: string | readonly string[], options?: AcquisitionOptions, ctx?: Context): DynamicReference;
|
|
16
|
+
/** Release the acquired claim if activation fails. */
|
|
17
|
+
get(service: string, key: string | readonly string[], options?: AcquisitionOptions, ctx?: Context): Promise<DynamicReference>;
|
|
18
|
+
/** Require a reference issued by this session. */
|
|
19
|
+
reference(value: unknown): ReferenceRecord;
|
|
20
|
+
/** Cache native orb metadata once per version. */
|
|
21
|
+
private orbMetadata;
|
|
22
|
+
/** Intersect declared requirements with current access permissions. */
|
|
23
|
+
private referenceMethods;
|
|
24
|
+
/** Update only references indexed under the changed object. */
|
|
25
|
+
refreshReferences(object: ObjectRecord, orb: OrbRecord): void;
|
|
26
|
+
/** Native claim release can precede its asynchronous metadata notification. */
|
|
27
|
+
private claimExists;
|
|
28
|
+
/** Detach state observers and remove local reference indexes. */
|
|
29
|
+
private forget;
|
|
30
|
+
/** Release the kernel claim and local observers once. */
|
|
31
|
+
release(id: number): void;
|
|
32
|
+
/** Revokes a JS handle after the engine has released its claim. */
|
|
33
|
+
revoke(id: number): void;
|
|
34
|
+
/** Remove cached metadata for a retired orb version. */
|
|
35
|
+
retire(orb: number): void;
|
|
36
|
+
/** Detach all remaining observers during host shutdown. */
|
|
37
|
+
clear(): void;
|
|
38
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { OrbDefinition, PreparedReload, ReloadOptions, ReloadReport } from "../authoring/types.ts";
|
|
2
|
+
import type { Session } from "./session.ts";
|
|
3
|
+
/** Captures JS factories and exposes the engine's transaction handle. No reload policy lives here. */
|
|
4
|
+
export declare class Replacements {
|
|
5
|
+
#private;
|
|
6
|
+
readonly session: Session;
|
|
7
|
+
/** Track one replacement candidate for this session. */
|
|
8
|
+
constructor(session: Session);
|
|
9
|
+
/** Prepare and commit a replacement in one operation. */
|
|
10
|
+
replace(definitions: readonly OrbDefinition[], options?: ReloadOptions, remove?: readonly string[]): Promise<ReloadReport>;
|
|
11
|
+
/** Reject overlapping replacement attempts before capturing callbacks. */
|
|
12
|
+
prepare(definitions: readonly OrbDefinition[], options?: ReloadOptions, remove?: readonly string[]): Promise<PreparedReload>;
|
|
13
|
+
/** Abort pending preparation and wait for physical recovery. */
|
|
14
|
+
cancel(): Promise<void>;
|
|
15
|
+
/** Bind candidate callbacks to the kernel's prepared replacement. */
|
|
16
|
+
private capture;
|
|
17
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { ResourceOptions } from "../authoring/types.ts";
|
|
2
|
+
import type { Environment, ResourceRecord } from "./records.ts";
|
|
3
|
+
import type { Session } from "./session.ts";
|
|
4
|
+
export declare class Resources {
|
|
5
|
+
readonly session: Session;
|
|
6
|
+
readonly records: Map<number, ResourceRecord>;
|
|
7
|
+
readonly closedRecords: Map<number, ResourceRecord>;
|
|
8
|
+
/** Retain callbacks for live and closed resource identities. */
|
|
9
|
+
constructor(session: Session);
|
|
10
|
+
/** Resolve a live or recently closed callback record by its kernel identity. */
|
|
11
|
+
find(id: number): ResourceRecord | undefined;
|
|
12
|
+
/** Validate local dependency ownership and collect resource identities. */
|
|
13
|
+
dependencyIds(options: ResourceOptions<any>): number[];
|
|
14
|
+
/** Ask Rust to resolve this named resource declaration. */
|
|
15
|
+
private register;
|
|
16
|
+
/** Rebind closed host resources to a fresh declared scope. */
|
|
17
|
+
redeclare(environment: Environment, previous: Environment): void;
|
|
18
|
+
/** Issue a local resource handle and retain its physical callbacks. */
|
|
19
|
+
declare<T>(environment: Environment, name: string, options: ResourceOptions<T>): ResourceRecord;
|
|
20
|
+
/** Wait for opening and closing callbacks before acknowledging release. */
|
|
21
|
+
close(record: ResourceRecord): Promise<void>;
|
|
22
|
+
/** Rebind a restored resource and wait for its new value. */
|
|
23
|
+
reopen(record: ResourceRecord, id: number): Promise<void>;
|
|
24
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { Resource, ResourceOptions } from "../authoring/types.ts";
|
|
2
|
+
import type { Acquisition, Owner } from "../bridge/kernel.ts";
|
|
3
|
+
import type { Environment, OrbRecord, ObjectRecord } from "./records.ts";
|
|
4
|
+
import type { Session } from "./session.ts";
|
|
5
|
+
/** Declare JS scopes and execute activation effects. */
|
|
6
|
+
export declare class Scopes {
|
|
7
|
+
#private;
|
|
8
|
+
readonly session: Session;
|
|
9
|
+
/** Track host resource names and pending host activations. */
|
|
10
|
+
constructor(session: Session);
|
|
11
|
+
/** Allocate the JS callback storage for one declared scope. */
|
|
12
|
+
environment(owner: Owner, orb: OrbRecord, object?: ObjectRecord): Environment;
|
|
13
|
+
/** Declare native or JS object scopes and wait for readiness. */
|
|
14
|
+
activate(object: ObjectRecord, acquired: Acquisition): Promise<void>;
|
|
15
|
+
/** Run a service factory synchronously and register its scope. */
|
|
16
|
+
createEnvironment(object: ObjectRecord, orb: OrbRecord): Environment;
|
|
17
|
+
/** Share host activation and reopen retired resource scopes. */
|
|
18
|
+
readyHostScope(): Promise<void>;
|
|
19
|
+
/** Clean up the previous scope before rebinding its resources. */
|
|
20
|
+
private redeclareHostScope;
|
|
21
|
+
/** Resolve a declared dependency and its allowed methods. */
|
|
22
|
+
requirement(environment: Environment, service: string): {
|
|
23
|
+
service: string;
|
|
24
|
+
apiVersion?: number;
|
|
25
|
+
methods?: readonly string[];
|
|
26
|
+
};
|
|
27
|
+
/** Require a named resource declared by this host. */
|
|
28
|
+
hostResource<T>(name: string): Resource<T>;
|
|
29
|
+
/** Add a host-owned resource and schedule its activation. */
|
|
30
|
+
resource<T>(name: string, options: ResourceOptions<T>): Resource<T>;
|
|
31
|
+
/** Index resources declared by the initial host scope. */
|
|
32
|
+
registerHost(environment: Environment): void;
|
|
33
|
+
/** Drop host resource indexes during shutdown. */
|
|
34
|
+
clear(): void;
|
|
35
|
+
}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type { HostOptions } from "../authoring/types.ts";
|
|
2
|
+
import type { Invocation, Snapshot } from "../bridge/kernel.ts";
|
|
3
|
+
import { Kernel } from "../bridge/kernel.ts";
|
|
4
|
+
import { TembraError } from "../error.ts";
|
|
5
|
+
import type { StateBackend } from "../state.ts";
|
|
6
|
+
import { Telemetry } from "../telemetry.ts";
|
|
7
|
+
import { Values } from "../values.ts";
|
|
8
|
+
import { Activities } from "./activities.ts";
|
|
9
|
+
import { Calls } from "./calls.ts";
|
|
10
|
+
import { Orbs } from "./orbs.ts";
|
|
11
|
+
import { Lifecycle } from "./lifecycle.ts";
|
|
12
|
+
import { Programs } from "./programs.ts";
|
|
13
|
+
import type { Environment, ObjectRecord, ReferenceRecord } from "./records.ts";
|
|
14
|
+
import { References } from "./references.ts";
|
|
15
|
+
import { Replacements } from "./reload.ts";
|
|
16
|
+
import { Resources } from "./resources.ts";
|
|
17
|
+
import { Scopes } from "./scopes.ts";
|
|
18
|
+
/** Shared JS values and callbacks. Rust owns lifecycle policy. */
|
|
19
|
+
export declare class Session implements StateBackend {
|
|
20
|
+
#private;
|
|
21
|
+
readonly options: HostOptions;
|
|
22
|
+
readonly contextTokens: WeakMap<object, {
|
|
23
|
+
root: number;
|
|
24
|
+
source: number;
|
|
25
|
+
}>;
|
|
26
|
+
readonly calls: Calls;
|
|
27
|
+
readonly handles: References;
|
|
28
|
+
readonly scopes: Scopes;
|
|
29
|
+
readonly lifecycle: Lifecycle;
|
|
30
|
+
readonly kernel: Kernel;
|
|
31
|
+
readonly values: Values;
|
|
32
|
+
readonly resources: Resources;
|
|
33
|
+
readonly activities: Activities;
|
|
34
|
+
readonly orbs: Orbs;
|
|
35
|
+
readonly replacements: Replacements;
|
|
36
|
+
readonly programs: Programs;
|
|
37
|
+
readonly objects: Map<number, ObjectRecord>;
|
|
38
|
+
readonly references: Map<number, ReferenceRecord>;
|
|
39
|
+
readonly rootReferences: Map<number, Set<number>>;
|
|
40
|
+
readonly controllers: Map<number, AbortController>;
|
|
41
|
+
readonly jobs: Set<Promise<unknown>>;
|
|
42
|
+
readonly cleanupErrors: unknown[];
|
|
43
|
+
hostScope: Environment;
|
|
44
|
+
readonly codec: import("../codec.ts").Codec;
|
|
45
|
+
readonly name: string;
|
|
46
|
+
readonly principal: string;
|
|
47
|
+
readonly errors: TembraError[];
|
|
48
|
+
readonly now: () => number;
|
|
49
|
+
readonly telemetry: Telemetry | undefined;
|
|
50
|
+
closing: boolean;
|
|
51
|
+
/** Create callback storage around one Rust lifecycle kernel. */
|
|
52
|
+
constructor(options: HostOptions);
|
|
53
|
+
/** Read the object owner, or use the host identity. */
|
|
54
|
+
principalFor(object: number): string;
|
|
55
|
+
/** Read the current value identity and state revision. */
|
|
56
|
+
snapshot(object: number): Snapshot;
|
|
57
|
+
/** Resolve a local value or cache its native decoded value. */
|
|
58
|
+
value<T>(id: number): T;
|
|
59
|
+
/** Require an admitted call for the target state owner. */
|
|
60
|
+
check(value: unknown, object: number): Invocation;
|
|
61
|
+
/** Publish candidate state only if its expected revision still matches. */
|
|
62
|
+
adopt(object: number, value: unknown, revision: string, candidate: unknown): Snapshot;
|
|
63
|
+
/** Serialize notifications so reentrant updates preserve publication order. */
|
|
64
|
+
publish(operation: () => void): void;
|
|
65
|
+
/** Retain a bounded error history without disrupting state adoption. */
|
|
66
|
+
report(error: unknown): void;
|
|
67
|
+
/** Retain physical work until settlement, including cancelled callers. */
|
|
68
|
+
track<T>(job: Promise<T>, cleanup?: boolean): Promise<T>;
|
|
69
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { PreparedSelection, Readable, State, StateBackend, StateOptions } from "./types.ts";
|
|
2
|
+
/** One object-owned state binding, shared by compatible implementation versions. */
|
|
3
|
+
export declare class StateBinding<T = unknown> {
|
|
4
|
+
#private;
|
|
5
|
+
readonly backend: StateBackend;
|
|
6
|
+
readonly object: number;
|
|
7
|
+
closed: boolean;
|
|
8
|
+
/** Bind an object's current state, optionally using a staged initial value. */
|
|
9
|
+
constructor(backend: StateBackend, object: number, initial?: Readonly<T>);
|
|
10
|
+
/** Reject state access after object cleanup. */
|
|
11
|
+
check(): void;
|
|
12
|
+
/** Read current state while its owner remains live. */
|
|
13
|
+
get value(): Readonly<T>;
|
|
14
|
+
/** Expose validated updates under the declaring orb's state contract. */
|
|
15
|
+
view(options: StateOptions<T>, check?: () => void): State<T>;
|
|
16
|
+
/** Track a derived value without retaining unused selections strongly. */
|
|
17
|
+
select<R>(compute: (value: Readonly<T>) => R, check?: () => void, cleanups?: Set<() => void>): Readable<R>;
|
|
18
|
+
/** Deliver current state immediately and report listener failures. */
|
|
19
|
+
subscribe(listener: (value: Readonly<T>) => void): () => void;
|
|
20
|
+
/** Compute live selections before changing the adopted value. */
|
|
21
|
+
prepare(candidate: Readonly<T>): PreparedSelection[];
|
|
22
|
+
/** Replace state and return its deferred notification pass. */
|
|
23
|
+
adopt(prepared: PreparedSelection[], candidate: Readonly<T>): () => void;
|
|
24
|
+
/** Release state and detach all tracked observers. */
|
|
25
|
+
close(): void;
|
|
26
|
+
}
|
|
27
|
+
/** Protect plain data and apply the orb's synchronous guard. */
|
|
28
|
+
export declare function validate<T>(candidate: T, options: StateOptions<T>): Readonly<T>;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { PreparedSelection, Readable } from "./types.ts";
|
|
2
|
+
export declare class Selection<T, R> implements Readable<R> {
|
|
3
|
+
#private;
|
|
4
|
+
readonly compute: (value: Readonly<T>) => R;
|
|
5
|
+
readonly report: (error: unknown) => void;
|
|
6
|
+
readonly check: () => void;
|
|
7
|
+
/** Compute and protect the initial selected value. */
|
|
8
|
+
constructor(compute: (value: Readonly<T>) => R, value: Readonly<T>, report: (error: unknown) => void, check: () => void);
|
|
9
|
+
/** Read the cached value while its owning reference remains valid. */
|
|
10
|
+
get value(): Readonly<R>;
|
|
11
|
+
/** Attach weak cleanup so the owner can release this selection. */
|
|
12
|
+
track(cleanups: Set<() => void> | undefined, remove: () => void): void;
|
|
13
|
+
/** Release listeners and child selections once. */
|
|
14
|
+
detach(): void;
|
|
15
|
+
/** Stage derived values before any state notification runs. */
|
|
16
|
+
prepare(value: Readonly<T>): PreparedSelection | undefined;
|
|
17
|
+
/** Derive a child selection with the same validity rule. */
|
|
18
|
+
select<S>(compute: (value: Readonly<R>) => S): Readable<S>;
|
|
19
|
+
/** Deliver the current value and retain a change listener. */
|
|
20
|
+
subscribe(listener: (value: Readonly<R>) => void): () => void;
|
|
21
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { Invocation, Snapshot } from "../bridge/kernel.ts";
|
|
2
|
+
export interface Readable<T> {
|
|
3
|
+
readonly value: Readonly<T>;
|
|
4
|
+
/** Derive a cached readable value from this source. */
|
|
5
|
+
select<R>(compute: (value: Readonly<T>) => R): Readable<R>;
|
|
6
|
+
/** Deliver the current value, then changes, until detached. */
|
|
7
|
+
subscribe(listener: (value: Readonly<T>) => void): () => void;
|
|
8
|
+
}
|
|
9
|
+
export interface StateOptions<T> {
|
|
10
|
+
version?: number;
|
|
11
|
+
validate?: (candidate: Readonly<T>) => boolean | void;
|
|
12
|
+
migrate?: (previous: unknown, fromVersion: number) => T;
|
|
13
|
+
}
|
|
14
|
+
export interface StateBackend {
|
|
15
|
+
/** Read value identity and revision from the kernel. */
|
|
16
|
+
snapshot(object: number): Snapshot;
|
|
17
|
+
/** Resolve an adapter-owned value identity. */
|
|
18
|
+
value<T>(id: number): T;
|
|
19
|
+
/** Adopt state only under the expected revision and admitted call. */
|
|
20
|
+
adopt(object: number, context: unknown, expected: string, candidate: unknown): Snapshot;
|
|
21
|
+
/** Require a live call that owns this object. */
|
|
22
|
+
check(context: unknown, object: number): Invocation;
|
|
23
|
+
/** Report observer failures without reverting adopted state. */
|
|
24
|
+
report(error: unknown): void;
|
|
25
|
+
/** Queue notifications in adoption order. */
|
|
26
|
+
publish(operation: () => void): void;
|
|
27
|
+
}
|
|
28
|
+
export interface State<T> extends Readable<T> {
|
|
29
|
+
/** Validate and adopt a synchronous candidate under the supplied context. */
|
|
30
|
+
update(context: unknown, change: (current: Readonly<T>) => T): Readonly<T>;
|
|
31
|
+
}
|
|
32
|
+
export interface PreparedSelection {
|
|
33
|
+
/** Publish the staged value and return its notification callback. */
|
|
34
|
+
adopt(): () => void;
|
|
35
|
+
}
|
package/dist/state.d.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { Outcome } from "./bridge/protocol.ts";
|
|
2
|
+
export interface Trace {
|
|
3
|
+
service: string;
|
|
4
|
+
method: string;
|
|
5
|
+
root: number;
|
|
6
|
+
codeVersion: number;
|
|
7
|
+
duration: number;
|
|
8
|
+
outcome: Outcome;
|
|
9
|
+
}
|
|
10
|
+
/** Bounded opt-in timing. Exporters remain an infrastructure concern. */
|
|
11
|
+
export declare class Telemetry {
|
|
12
|
+
#private;
|
|
13
|
+
readonly capacity: number;
|
|
14
|
+
readonly sampleEvery: number;
|
|
15
|
+
/** Configure a bounded buffer with a fixed sampling interval. */
|
|
16
|
+
constructor(capacity?: number, sampleEvery?: number);
|
|
17
|
+
/** Select calls at the configured sampling interval. */
|
|
18
|
+
sample(): boolean;
|
|
19
|
+
/** Append one sampled call, replacing the oldest record when full. */
|
|
20
|
+
record(trace: Trace): void;
|
|
21
|
+
/** Return buffered samples and clear their retained references. */
|
|
22
|
+
drain(): readonly Trace[];
|
|
23
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// src/telemetry.ts
|
|
2
|
+
class Telemetry {
|
|
3
|
+
capacity;
|
|
4
|
+
sampleEvery;
|
|
5
|
+
#events = [];
|
|
6
|
+
#next = 0;
|
|
7
|
+
constructor(capacity = 256, sampleEvery = 1) {
|
|
8
|
+
this.capacity = capacity;
|
|
9
|
+
this.sampleEvery = sampleEvery;
|
|
10
|
+
if (!Number.isInteger(capacity) || capacity <= 0 || !Number.isInteger(sampleEvery) || sampleEvery <= 0)
|
|
11
|
+
throw new RangeError("Invalid telemetry limits");
|
|
12
|
+
}
|
|
13
|
+
sample() {
|
|
14
|
+
return this.#next++ % this.sampleEvery === 0;
|
|
15
|
+
}
|
|
16
|
+
record(trace) {
|
|
17
|
+
if (this.#events.length === this.capacity)
|
|
18
|
+
this.#events.shift();
|
|
19
|
+
this.#events.push(trace);
|
|
20
|
+
}
|
|
21
|
+
drain() {
|
|
22
|
+
return this.#events.splice(0);
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
export {
|
|
26
|
+
Telemetry
|
|
27
|
+
};
|