@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.
Files changed (134) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +47 -2
  3. package/dist/authoring/declaration.d.ts +48 -0
  4. package/dist/authoring/hooks.d.ts +11 -0
  5. package/dist/authoring/orb.d.ts +3 -0
  6. package/dist/authoring/service-identities.d.ts +7 -0
  7. package/dist/authoring/services.d.ts +8 -0
  8. package/dist/authoring/types.d.ts +181 -0
  9. package/dist/bridge/identifiers.d.ts +207 -0
  10. package/dist/bridge/kernel.d.ts +117 -0
  11. package/dist/bridge/protocol.d.ts +181 -0
  12. package/dist/browser.d.ts +21 -0
  13. package/dist/browser.js +3335 -0
  14. package/dist/codec.d.ts +1 -0
  15. package/dist/codecs/json.d.ts +13 -0
  16. package/dist/codecs/msgpack.d.ts +3 -0
  17. package/dist/context-key.d.ts +35 -0
  18. package/dist/coordinator.d.ts +1 -0
  19. package/dist/coordinator.js +543 -0
  20. package/dist/embedded.d.ts +1 -0
  21. package/dist/embedded.js +1 -0
  22. package/dist/error.d.ts +13 -0
  23. package/dist/errors.d.ts +122 -0
  24. package/dist/hooks.d.ts +1 -0
  25. package/dist/host.d.ts +98 -0
  26. package/dist/host.js +3278 -0
  27. package/dist/identifiers.d.ts +1 -0
  28. package/dist/index.d.ts +12 -0
  29. package/dist/index.js +864 -0
  30. package/dist/infrastructure/coordinator.d.ts +13 -0
  31. package/dist/infrastructure/manager.d.ts +23 -0
  32. package/dist/infrastructure/rpc/channel.d.ts +55 -0
  33. package/dist/infrastructure/rpc/client.d.ts +20 -0
  34. package/dist/infrastructure/rpc/server.d.ts +10 -0
  35. package/dist/infrastructure/rpc/state.d.ts +16 -0
  36. package/dist/kernel.d.ts +1 -0
  37. package/dist/manager.d.ts +1 -0
  38. package/dist/manager.js +390 -0
  39. package/dist/msgpack.d.ts +1 -0
  40. package/dist/msgpack.js +635 -0
  41. package/dist/node.d.ts +14 -0
  42. package/dist/node.js +3336 -0
  43. package/dist/orb.d.ts +1 -0
  44. package/dist/protocol.d.ts +1 -0
  45. package/dist/rpc.d.ts +3 -0
  46. package/dist/rpc.js +1091 -0
  47. package/dist/runtime/activities.d.ts +30 -0
  48. package/dist/runtime/calls.d.ts +22 -0
  49. package/dist/runtime/context.d.ts +38 -0
  50. package/dist/runtime/declaration.d.ts +1 -0
  51. package/dist/runtime/lifecycle.d.ts +28 -0
  52. package/dist/runtime/orbs.d.ts +39 -0
  53. package/dist/runtime/programs.d.ts +31 -0
  54. package/dist/runtime/records.d.ts +107 -0
  55. package/dist/runtime/references.d.ts +38 -0
  56. package/dist/runtime/reload.d.ts +17 -0
  57. package/dist/runtime/resources.d.ts +24 -0
  58. package/dist/runtime/scopes.d.ts +35 -0
  59. package/dist/runtime/session.d.ts +69 -0
  60. package/dist/state/binding.d.ts +28 -0
  61. package/dist/state/selection.d.ts +21 -0
  62. package/dist/state/types.d.ts +35 -0
  63. package/dist/state.d.ts +2 -0
  64. package/dist/telemetry.d.ts +23 -0
  65. package/dist/telemetry.js +27 -0
  66. package/dist/tooling/build.d.ts +3 -0
  67. package/dist/tooling/index.d.ts +2 -0
  68. package/dist/tooling/index.js +181 -0
  69. package/dist/tooling/resolver.d.ts +5 -0
  70. package/dist/tooling/typecheck.d.ts +2 -0
  71. package/dist/tooling/types.d.ts +29 -0
  72. package/dist/types.d.ts +1 -0
  73. package/dist/values.d.ts +23 -0
  74. package/package.json +103 -4
  75. package/src/authoring/declaration.ts +237 -0
  76. package/src/authoring/hooks.ts +101 -0
  77. package/src/authoring/orb.ts +88 -0
  78. package/src/authoring/service-identities.ts +20 -0
  79. package/src/authoring/services.ts +46 -0
  80. package/src/authoring/types.ts +256 -0
  81. package/src/bridge/identifiers.ts +212 -0
  82. package/src/bridge/kernel.ts +117 -0
  83. package/src/bridge/protocol.ts +193 -0
  84. package/src/browser.ts +59 -0
  85. package/src/codec.ts +1 -0
  86. package/src/codecs/json.ts +147 -0
  87. package/src/codecs/msgpack.ts +26 -0
  88. package/src/context-key.ts +94 -0
  89. package/src/coordinator.ts +1 -0
  90. package/src/embedded.ts +293 -0
  91. package/src/error.ts +50 -0
  92. package/src/errors.ts +237 -0
  93. package/src/hooks.ts +1 -0
  94. package/src/host.ts +173 -0
  95. package/src/identifiers.ts +1 -0
  96. package/src/index.ts +22 -0
  97. package/src/infrastructure/coordinator.ts +76 -0
  98. package/src/infrastructure/manager.ts +77 -0
  99. package/src/infrastructure/rpc/channel.ts +107 -0
  100. package/src/infrastructure/rpc/client.ts +216 -0
  101. package/src/infrastructure/rpc/server.ts +201 -0
  102. package/src/infrastructure/rpc/state.ts +70 -0
  103. package/src/kernel.ts +1 -0
  104. package/src/manager.ts +1 -0
  105. package/src/msgpack.ts +1 -0
  106. package/src/node.ts +53 -0
  107. package/src/orb.ts +1 -0
  108. package/src/protocol.ts +1 -0
  109. package/src/rpc.ts +3 -0
  110. package/src/runtime/activities.ts +197 -0
  111. package/src/runtime/calls.ts +165 -0
  112. package/src/runtime/context.ts +128 -0
  113. package/src/runtime/declaration.ts +1 -0
  114. package/src/runtime/lifecycle.ts +227 -0
  115. package/src/runtime/orbs.ts +292 -0
  116. package/src/runtime/programs.ts +274 -0
  117. package/src/runtime/records.ts +127 -0
  118. package/src/runtime/references.ts +406 -0
  119. package/src/runtime/reload.ts +161 -0
  120. package/src/runtime/resources.ts +157 -0
  121. package/src/runtime/scopes.ts +210 -0
  122. package/src/runtime/session.ts +181 -0
  123. package/src/state/binding.ts +157 -0
  124. package/src/state/selection.ts +122 -0
  125. package/src/state/types.ts +47 -0
  126. package/src/state.ts +2 -0
  127. package/src/telemetry.ts +45 -0
  128. package/src/tooling/build.ts +83 -0
  129. package/src/tooling/index.ts +8 -0
  130. package/src/tooling/resolver.ts +95 -0
  131. package/src/tooling/typecheck.ts +32 -0
  132. package/src/tooling/types.ts +32 -0
  133. package/src/types.ts +1 -0
  134. package/src/values.ts +85 -0
@@ -0,0 +1,197 @@
1
+ import { EnvironmentPhase, KernelOp } from "../bridge/protocol.ts";
2
+ import { Errors } from "../errors.ts";
3
+
4
+ import { refuse, TembraError } from "../error.ts";
5
+ import type { Environment, ListenerRecord, TaskDefinition, TaskRecord } from "./records.ts";
6
+ import type { Session } from "./session.ts";
7
+
8
+ export class Activities {
9
+ readonly tasks = new Map<number, TaskRecord>();
10
+ readonly listeners = new Map<number, ListenerRecord>();
11
+ #identities = new WeakMap<object, number>();
12
+
13
+ /** Keep task and listener callbacks for this session. */
14
+ constructor(readonly session: Session) {}
15
+
16
+ /** Attach declared sources using subscription identities issued by Rust. */
17
+ prepare(environment: Environment, previous?: Environment): void {
18
+ for (const definition of environment.listeners) {
19
+ const source =
20
+ typeof definition.source === "function" ? definition.source() : definition.source;
21
+ if (!source || typeof source.subscribe !== "function") refuse(Errors.Invalid.EventSource);
22
+ const id = this.session.kernel.command<number>(KernelOp.Listen, {
23
+ scope: environment.id,
24
+ previous: previous?.id,
25
+ name: definition.name,
26
+ source: this.identity(source),
27
+ sizing: definition.options.sizeOf ? this.identity(definition.options.sizeOf) : 0,
28
+ operation: this.session.kernel.command<number>(KernelOp.Allocate),
29
+ maxPending: definition.options.maxPending ?? 64,
30
+ ...(definition.options.maxBytes ? { maxBytes: definition.options.maxBytes } : {}),
31
+ coalesce: "select" in source,
32
+ });
33
+ const existing = this.listeners.get(id);
34
+ if (existing) {
35
+ definition.running = existing;
36
+ continue;
37
+ }
38
+ const record: ListenerRecord = {
39
+ id,
40
+ definition,
41
+ environment,
42
+ stopped: false,
43
+ /** Allow safe stop before the source returns its detach callback. */
44
+ detach() {},
45
+ };
46
+ definition.running = record;
47
+ this.listeners.set(id, record);
48
+ try {
49
+ record.detach = source.subscribe((value) => {
50
+ if (record.stopped) return;
51
+ const payload = this.session.values.put(value);
52
+ try {
53
+ const bytes = definition.options.sizeOf?.(value) ?? 0;
54
+ if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > 0xffff_ffff)
55
+ throw new TembraError(Errors.Invalid.SubscriptionSize);
56
+ this.session.kernel.command(KernelOp.Enqueue, { subscription: id, payload, bytes });
57
+ } catch (error) {
58
+ this.session.values.drop(payload);
59
+ this.session.report(error);
60
+ this.failed(id);
61
+ }
62
+ this.session.lifecycle.flush();
63
+ });
64
+ if (record.stopped) record.detach();
65
+ } catch (error) {
66
+ this.stopListener(record);
67
+ throw error;
68
+ }
69
+ }
70
+ }
71
+
72
+ /** Start tasks and retarget listeners after scope adoption. */
73
+ start(environment: Environment): void {
74
+ environment.phase = EnvironmentPhase.Live;
75
+ for (const definition of environment.listeners) {
76
+ const record = definition.running!;
77
+ record.environment = environment;
78
+ record.definition = definition;
79
+ }
80
+ for (const task of environment.tasks) this.startTask(environment, task);
81
+ }
82
+
83
+ /** Run one task until its physical callback settles. */
84
+ private startTask(environment: Environment, definition: TaskDefinition): void {
85
+ if (definition.running || environment.phase !== EnvironmentPhase.Live || this.session.closing)
86
+ return;
87
+ const id = this.session.kernel.command<number>(KernelOp.Task, { owner: environment.owner });
88
+ const controller = new AbortController();
89
+ const operation = this.session.kernel.command<number>(KernelOp.Allocate);
90
+ const record: TaskRecord = { id, controller, done: Promise.resolve() };
91
+ definition.running = record;
92
+ this.tasks.set(id, record);
93
+ record.done = this.session.track(
94
+ Promise.resolve().then(async () => {
95
+ try {
96
+ await definition.start({
97
+ signal: controller.signal,
98
+ /** Issue operation authority under the task's retained version. */
99
+ root: (callback) => {
100
+ const root = this.session.kernel.command<number>(KernelOp.TaskRoot, {
101
+ task: id,
102
+ principal: this.session.principalFor(environment.object?.id ?? 0),
103
+ });
104
+ return this.session.calls.root(
105
+ () => this.session.calls.owned(environment, operation, callback, root),
106
+ false,
107
+ root,
108
+ );
109
+ },
110
+ });
111
+ } catch (error) {
112
+ if (!controller.signal.aborted) this.session.report(error);
113
+ } finally {
114
+ this.session.kernel.command(KernelOp.Tick, { now: this.session.now() });
115
+ this.session.kernel.command(KernelOp.FinishTask, { task: id });
116
+ this.tasks.delete(id);
117
+ delete definition.running;
118
+ this.session.lifecycle.flush();
119
+ }
120
+ }),
121
+ );
122
+ }
123
+
124
+ /** Reuse one kernel identity for the same source or sizing callback. */
125
+ private identity(value: object): number {
126
+ let id = this.#identities.get(value);
127
+ if (id === undefined) {
128
+ id = this.session.kernel.command<number>(KernelOp.Allocate);
129
+ this.#identities.set(value, id);
130
+ }
131
+ return id;
132
+ }
133
+
134
+ /** Execute an admitted delivery and acknowledge physical settlement. */
135
+ deliver(subscription: number, payload: number, operation: number): void {
136
+ const record = this.listeners.get(subscription);
137
+ const job = Promise.resolve().then(async () => {
138
+ try {
139
+ if (!record) throw new TembraError(Errors.Gone.ListenerCallback);
140
+ await this.session.calls.owned(record.environment, operation, (ctx) =>
141
+ record.definition.handle(ctx, this.session.values.get(payload)),
142
+ );
143
+ } catch (error) {
144
+ this.session.report(error);
145
+ } finally {
146
+ this.session.kernel.command(KernelOp.FinishDelivery, { subscription });
147
+ this.session.lifecycle.flush();
148
+ }
149
+ });
150
+ if (record) record.done = job;
151
+ this.session.track(job);
152
+ }
153
+
154
+ /** Stop a listener selected by the kernel. */
155
+ detach(id: number): void {
156
+ const record = this.listeners.get(id);
157
+ if (record) this.stopListener(record);
158
+ }
159
+
160
+ /** Signal task cancellation without releasing its ownership. */
161
+ cancel(id: number): void {
162
+ this.tasks.get(id)?.controller.abort(new TembraError(Errors.Cancelled.Task));
163
+ }
164
+
165
+ /** Report queue exhaustion and stop its source listener. */
166
+ failed(id: number): void {
167
+ const record = this.listeners.get(id);
168
+ if (!record) return;
169
+ this.session.report(new TembraError(Errors.Exhausted.SubscriptionQueue));
170
+ this.stopListener(record);
171
+ }
172
+
173
+ /** Detach the source and release its kernel subscription once. */
174
+ private stopListener(record: ListenerRecord): void {
175
+ if (record.stopped) return;
176
+ record.stopped = true;
177
+ try {
178
+ record.detach();
179
+ } catch (error) {
180
+ this.session.report(error);
181
+ }
182
+ this.session.kernel.command(KernelOp.Unsubscribe, { subscription: record.id });
183
+ this.listeners.delete(record.id);
184
+ this.session.lifecycle.flush();
185
+ }
186
+
187
+ /** Wait for owned tasks and admitted deliveries to settle. */
188
+ async stop(environment: Environment): Promise<void> {
189
+ for (const definition of environment.tasks) {
190
+ if (definition.running)
191
+ this.session.kernel.command(KernelOp.StopTask, { task: definition.running.id });
192
+ }
193
+ this.session.lifecycle.flush();
194
+ await Promise.all(environment.tasks.map((task) => task.running?.done));
195
+ await Promise.all(environment.listeners.map((listener) => listener.running?.done));
196
+ }
197
+ }
@@ -0,0 +1,165 @@
1
+ import type { Completion } from "../authoring/types.ts";
2
+ import { Code } from "../bridge/identifiers.ts";
3
+ import type { Invocation } from "../bridge/kernel.ts";
4
+ import { KernelOp, Outcome } from "../bridge/protocol.ts";
5
+ import { TembraError } from "../error.ts";
6
+ import { Errors } from "../errors.ts";
7
+ import { Context, context } from "./context.ts";
8
+ import type { Environment, ReferenceRecord } from "./records.ts";
9
+ import type { Session } from "./session.ts";
10
+
11
+ /** Execute JS calls. Rust controls admission and physical lifetime. */
12
+ export class Calls {
13
+ /** Connect JS callback execution to the session kernel. */
14
+ constructor(readonly session: Session) {}
15
+
16
+ /** Lazily mirror root cancellation into an AbortSignal. */
17
+ signal(root: number): AbortSignal {
18
+ const session = this.session;
19
+ let controller = session.controllers.get(root);
20
+ if (!controller) {
21
+ controller = new AbortController();
22
+ try {
23
+ session.kernel.command(KernelOp.CheckRoot, { root });
24
+ } catch (error) {
25
+ if (!(error instanceof TembraError) || error.code !== Code.Cancelled) throw error;
26
+ controller.abort(error);
27
+ }
28
+ session.controllers.set(root, controller);
29
+ }
30
+ return controller.signal;
31
+ }
32
+
33
+ /** Revoke claims and cancellation mirrors when either language ends a root. */
34
+ releaseRoot(root: number): void {
35
+ for (const reference of this.session.rootReferences.get(root) ?? [])
36
+ this.session.handles.release(reference);
37
+ this.session.rootReferences.delete(root);
38
+ this.session.controllers.delete(root);
39
+ }
40
+
41
+ /** Release root-owned references after the callback settles. */
42
+ async root<T>(
43
+ operation: (context: Context) => Completion<T>,
44
+ cleanup = false,
45
+ issuedRoot?: number,
46
+ principal = this.session.principal,
47
+ ): Promise<T> {
48
+ const session = this.session;
49
+ const root =
50
+ issuedRoot ??
51
+ session.kernel.command<number>(cleanup ? KernelOp.CleanupRoot : KernelOp.Root, { principal });
52
+ const ctx = new Context(session, root);
53
+ try {
54
+ return await operation(ctx);
55
+ } finally {
56
+ this.releaseRoot(root);
57
+ session.options.native?.rootEnded?.(root);
58
+ if (!session.lifecycle.closedDiagnostics) session.kernel.command(KernelOp.EndRoot, { root });
59
+ session.controllers.delete(root);
60
+ session.lifecycle.flush();
61
+ }
62
+ }
63
+
64
+ /** Execute one admitted service call and retain physical ownership. */
65
+ async invoke(
66
+ reference: ReferenceRecord,
67
+ method: string,
68
+ arguments_: unknown[],
69
+ ctx: Context,
70
+ ): Promise<unknown> {
71
+ const session = this.session;
72
+ context(ctx, session);
73
+ if (reference.released) throw new TembraError(Errors.Released.Reference);
74
+ await reference.ready;
75
+ const admission = session.options.native?.admit?.(reference.id, method, ctx);
76
+ let invocation: Invocation;
77
+ if (admission) invocation = admission.call;
78
+ else {
79
+ ctx.check();
80
+ invocation = session.kernel.command<Invocation>(KernelOp.BeginCall, {
81
+ reference: reference.id,
82
+ root: ctx.root,
83
+ context: ctx.frame || undefined,
84
+ method,
85
+ });
86
+ }
87
+ const entered = new Context(session, ctx.root, invocation, ctx.frame);
88
+ const physical = session.track(
89
+ (async () => {
90
+ const sampled = session.telemetry?.sample();
91
+ const started = sampled ? session.now() : 0;
92
+ let outcome: Outcome = Outcome.Ok;
93
+ try {
94
+ const native = session.options.native;
95
+ if (native && (admission?.native ?? native.hasOrb(invocation.orb)))
96
+ return await native.invoke(invocation, arguments_, entered);
97
+ const object = session.objects.get(invocation.object);
98
+ const environment = object?.versions.get(invocation.orb);
99
+ const handle =
100
+ environment?.orb.definition.services?.[reference.address.service]?.methods[method];
101
+ if (!environment || !handle) throw new TembraError(Errors.Gone.Implementation);
102
+ return await handle(environment.value, entered, ...arguments_);
103
+ } catch (error) {
104
+ outcome = Outcome.Error;
105
+ throw error;
106
+ } finally {
107
+ if (sampled)
108
+ session.telemetry!.record({
109
+ service: reference.address.service,
110
+ method,
111
+ root: invocation.root,
112
+ codeVersion: invocation.codeVersion,
113
+ duration: session.now() - started,
114
+ outcome,
115
+ });
116
+ session.lifecycle.finishCall(invocation.id);
117
+ }
118
+ })(),
119
+ );
120
+ return this.observe(physical, ctx.signal);
121
+ }
122
+
123
+ /** Fresh callback roots inherit owner identity; supplied roots retain the caller's authority. */
124
+ async owned<T>(
125
+ environment: Environment,
126
+ operation: number,
127
+ handle: (ctx: Context) => Completion<T>,
128
+ root?: number | Context,
129
+ ): Promise<T> {
130
+ const session = this.session;
131
+ const execute = async (ctx: Context) => {
132
+ const invocation = session.kernel.command<Invocation>(KernelOp.BeginOperation, {
133
+ orb: environment.orb.info.id,
134
+ root: ctx.root,
135
+ context: ctx.frame || undefined,
136
+ operation,
137
+ ...(environment.object ? { object: environment.object.id } : {}),
138
+ });
139
+ try {
140
+ return await handle(new Context(session, ctx.root, invocation, ctx.frame));
141
+ } finally {
142
+ session.kernel.command(KernelOp.FinishCall, { call: invocation.id });
143
+ session.lifecycle.flush();
144
+ }
145
+ };
146
+ return root === undefined
147
+ ? this.root(execute, false, undefined, session.principalFor(environment.object?.id ?? 0))
148
+ : execute(typeof root === "number" ? new Context(session, root) : root);
149
+ }
150
+
151
+ /** Stop waiting on cancellation while physical work remains tracked. */
152
+ async observe<T>(physical: Promise<T>, signal: AbortSignal): Promise<T> {
153
+ if (signal.aborted) throw signal.reason;
154
+ let abort!: () => void;
155
+ const cancelled = new Promise<never>((_, reject) => {
156
+ abort = () => reject(signal.reason ?? new TembraError(Errors.Cancelled.Root));
157
+ signal.addEventListener("abort", abort, { once: true });
158
+ });
159
+ try {
160
+ return await Promise.race([physical, cancelled]);
161
+ } finally {
162
+ signal.removeEventListener("abort", abort);
163
+ }
164
+ }
165
+ }
@@ -0,0 +1,128 @@
1
+ import { ContextKey, ContextKind, readContextValue } from "../context-key.ts";
2
+ import { KernelOp } from "../bridge/protocol.ts";
3
+ import { Errors } from "../errors.ts";
4
+
5
+ import type {
6
+ AcquisitionOptions,
7
+ DynamicReference,
8
+ ServiceDefinition,
9
+ ServiceReference,
10
+ } from "../authoring/types.ts";
11
+ import type { Invocation } from "../bridge/kernel.ts";
12
+ import { TembraError } from "../error.ts";
13
+ import type { Session } from "./session.ts";
14
+
15
+ const issued = new WeakMap<object, Context>();
16
+
17
+ /** An issued operation scope. Keeping this object does not extend its root or invocation. */
18
+ export class Context {
19
+ /** Issue a context for an existing root and optional admitted call. */
20
+ constructor(
21
+ readonly session: Session,
22
+ readonly root: number,
23
+ readonly invocation?: Invocation,
24
+ readonly frame: number = 0,
25
+ ) {
26
+ issued.set(this, this);
27
+ }
28
+
29
+ /** Derive one binding without changing identity or lifetime. */
30
+ with<T>(key: ContextKey<T>, value: T): Context {
31
+ const source = key.source(value, this);
32
+ const frame = this.session.kernel.command<number>(KernelOp.ContextDerive, {
33
+ root: this.root,
34
+ context: this.frame,
35
+ call: this.invocation?.id,
36
+ key,
37
+ ...(key.kind === ContextKind.Opaque ? { source } : { value }),
38
+ });
39
+ return new Context(this.session, this.root, this.invocation, frame);
40
+ }
41
+
42
+ /** Read the nearest binding of this typed key. */
43
+ value<T>(key: ContextKey<T>): T | undefined {
44
+ return readContextValue(this, key, this.frame);
45
+ }
46
+
47
+ /** Export only explicitly allowed scalar metadata. */
48
+ exportValues(keys: readonly ContextKey<unknown>[]): Record<string, unknown> {
49
+ const result: Record<string, unknown> = {};
50
+ for (const key of keys) {
51
+ if (key.kind === ContextKind.Opaque)
52
+ throw new TypeError("Local opaque references cannot be exported");
53
+ const value = this.value(key);
54
+ if (value !== undefined) result[`${key.name}@${key.version}`] = value;
55
+ }
56
+ return result;
57
+ }
58
+
59
+ /** Read the root identity from the kernel. */
60
+ get principal(): string {
61
+ return this.session.kernel.command<string>(KernelOp.RootPrincipal, { root: this.root });
62
+ }
63
+
64
+ /** Read the shared cancellation signal for this root. */
65
+ get signal(): AbortSignal {
66
+ return this.session.calls.signal(this.root);
67
+ }
68
+
69
+ /** Reject a cancelled root or expired invocation. */
70
+ check(): void {
71
+ this.session.kernel.command(KernelOp.CheckContext, {
72
+ root: this.root,
73
+ call: this.invocation?.id,
74
+ });
75
+ }
76
+
77
+ /** Cancel the root and dispatch its cancellation actions. */
78
+ cancel(): void {
79
+ this.session.kernel.command(KernelOp.CancelRoot, { root: this.root });
80
+ this.session.lifecycle.flush();
81
+ }
82
+
83
+ /** Acquire a reference whose claim ends with this root. */
84
+ get<const Service extends ServiceDefinition>(
85
+ service: Service,
86
+ key: string | readonly string[],
87
+ options?: AcquisitionOptions,
88
+ ): Promise<ServiceReference<Service>>;
89
+ get(
90
+ service: string,
91
+ key: string | readonly string[],
92
+ options?: AcquisitionOptions,
93
+ ): Promise<DynamicReference>;
94
+ get(
95
+ service: string | ServiceDefinition,
96
+ key: string | readonly string[],
97
+ options: AcquisitionOptions = {},
98
+ ): Promise<DynamicReference> {
99
+ this.check();
100
+ return this.session.handles.get(service, key, options, this);
101
+ }
102
+
103
+ /** Read a named host resource while the context remains valid. */
104
+ resource<T>(name: string): import("../authoring/types.ts").Resource<T> {
105
+ this.check();
106
+ return this.session.scopes.hostResource<T>(name);
107
+ }
108
+ }
109
+
110
+ /** Require a context issued by the same host without checking cancellation or expiry. */
111
+ export function issuedContext(value: unknown, session: Session): Context {
112
+ if (typeof value !== "object" || value === null || issued.get(value)?.session !== session) {
113
+ throw new TembraError(Errors.Forbidden.Context, "An issued context from this host is required");
114
+ }
115
+ return issued.get(value)!;
116
+ }
117
+
118
+ /** Require a live context issued by the same host. */
119
+ export function context(value: unknown, session: Session): Context {
120
+ const result = issuedContext(value, session);
121
+ result.check();
122
+ return result;
123
+ }
124
+
125
+ /** Recognize an issued context without extending its lifetime. */
126
+ export function isContext(value: unknown): value is Context {
127
+ return typeof value === "object" && value !== null && issued.has(value);
128
+ }
@@ -0,0 +1 @@
1
+ export * from "../authoring/declaration.ts";