@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,227 @@
|
|
|
1
|
+
import type { Action, Diagnostics } from "../bridge/kernel.ts";
|
|
2
|
+
import { ActionType, KernelOp, OwnerKind } from "../bridge/protocol.ts";
|
|
3
|
+
import { TembraError } from "../error.ts";
|
|
4
|
+
import { Errors } from "../errors.ts";
|
|
5
|
+
import type { Session } from "./session.ts";
|
|
6
|
+
|
|
7
|
+
/** Dispatch core actions and wait for physical shutdown. */
|
|
8
|
+
export class Lifecycle {
|
|
9
|
+
/** Connect kernel actions to JS cleanup and scheduling. */
|
|
10
|
+
constructor(readonly session: Session) {}
|
|
11
|
+
|
|
12
|
+
/** Read final counts after kernel storage has been released. */
|
|
13
|
+
get closedDiagnostics(): ReturnType<Lifecycle["diagnostics"]> | undefined {
|
|
14
|
+
return this.#finalDiagnostics;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
#closed?: Promise<void>;
|
|
18
|
+
#flushing = false;
|
|
19
|
+
#linger: ReturnType<typeof setTimeout> | undefined;
|
|
20
|
+
#lingerDeadline: number | undefined;
|
|
21
|
+
#finalDiagnostics: ReturnType<Lifecycle["diagnostics"]> | undefined;
|
|
22
|
+
|
|
23
|
+
/** Drain kernel actions without re-entering the dispatcher. */
|
|
24
|
+
flush(initial?: Action[]): void {
|
|
25
|
+
if (this.#flushing) return;
|
|
26
|
+
this.#flushing = true;
|
|
27
|
+
try {
|
|
28
|
+
for (;;) {
|
|
29
|
+
const actions = initial ?? this.session.kernel.command<Action[]>(KernelOp.Drain);
|
|
30
|
+
initial = undefined;
|
|
31
|
+
if (!actions.length) break;
|
|
32
|
+
for (const action of actions) {
|
|
33
|
+
try {
|
|
34
|
+
this.action(action);
|
|
35
|
+
} catch (error) {
|
|
36
|
+
this.session.report(error);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
} finally {
|
|
41
|
+
this.#flushing = false;
|
|
42
|
+
this.scheduleLinger();
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Compose kernel finish bookkeeping through the embedded adapter when available. */
|
|
47
|
+
finishCall(call: number): void {
|
|
48
|
+
const session = this.session;
|
|
49
|
+
if (!this.#flushing && session.options.native?.finish) {
|
|
50
|
+
const batch = session.options.native.finish(call, session.now());
|
|
51
|
+
if (!batch.actions.length) {
|
|
52
|
+
this.scheduleLinger(batch.deadline);
|
|
53
|
+
return;
|
|
54
|
+
}
|
|
55
|
+
this.flush(batch.actions);
|
|
56
|
+
return;
|
|
57
|
+
}
|
|
58
|
+
session.kernel.command(KernelOp.Tick, { now: session.now() });
|
|
59
|
+
session.kernel.command(KernelOp.FinishCall, { call });
|
|
60
|
+
this.flush();
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** Execute one action using its owning JS module. */
|
|
64
|
+
private action(action: Action): void {
|
|
65
|
+
const session = this.session;
|
|
66
|
+
const nativeHandled = session.options.native?.notify?.(action);
|
|
67
|
+
if (
|
|
68
|
+
nativeHandled &&
|
|
69
|
+
!(action.type === ActionType.ProgramComplete && session.programs.pending(action.id))
|
|
70
|
+
)
|
|
71
|
+
return;
|
|
72
|
+
switch (action.type) {
|
|
73
|
+
case ActionType.Execute:
|
|
74
|
+
case ActionType.CancelEffects:
|
|
75
|
+
case ActionType.ProgramPrepared:
|
|
76
|
+
case ActionType.ProgramComplete:
|
|
77
|
+
session.programs.dispatch(action);
|
|
78
|
+
break;
|
|
79
|
+
case ActionType.DropValue:
|
|
80
|
+
session.values.drop(action.id);
|
|
81
|
+
session.options.native?.dropValue?.(action.id);
|
|
82
|
+
break;
|
|
83
|
+
case ActionType.CancelRoot:
|
|
84
|
+
session.controllers.get(action.id)?.abort(new TembraError(Errors.Cancelled.Root));
|
|
85
|
+
break;
|
|
86
|
+
case ActionType.CancelTask:
|
|
87
|
+
session.activities.cancel(action.id);
|
|
88
|
+
break;
|
|
89
|
+
case ActionType.Deliver:
|
|
90
|
+
session.activities.deliver(action.id, action.payload!, action.operation!);
|
|
91
|
+
break;
|
|
92
|
+
case ActionType.DetachSubscription:
|
|
93
|
+
session.activities.detach(action.id);
|
|
94
|
+
break;
|
|
95
|
+
case ActionType.SubscriptionFailed:
|
|
96
|
+
session.activities.failed(action.id);
|
|
97
|
+
break;
|
|
98
|
+
case ActionType.Dispose:
|
|
99
|
+
session.track(this.dispose(action.id), true);
|
|
100
|
+
break;
|
|
101
|
+
case ActionType.CloseResource: {
|
|
102
|
+
// Resource callbacks execute only in response to the engine's ordered program effect.
|
|
103
|
+
break;
|
|
104
|
+
}
|
|
105
|
+
case ActionType.RetireOrb:
|
|
106
|
+
session.handles.retire(action.id);
|
|
107
|
+
session.orbs.retire(action.id);
|
|
108
|
+
break;
|
|
109
|
+
case ActionType.State: {
|
|
110
|
+
const object = session.objects.get(action.id);
|
|
111
|
+
if (!object?.binding) break;
|
|
112
|
+
const snapshot = session.snapshot(action.id);
|
|
113
|
+
// Local updates already staged their selectors. Foreign Rust updates enter JS only here.
|
|
114
|
+
if (!session.values.has(snapshot.value)) {
|
|
115
|
+
const candidate = session.value<any>(snapshot.value);
|
|
116
|
+
session.publish(object.binding.adopt(object.binding.prepare(candidate), candidate));
|
|
117
|
+
}
|
|
118
|
+
break;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/** Wait for object activation and cleanup before releasing its binding. */
|
|
124
|
+
private async dispose(id: number): Promise<void> {
|
|
125
|
+
const session = this.session;
|
|
126
|
+
const object = session.objects.get(id);
|
|
127
|
+
if (!object) {
|
|
128
|
+
// Native contexts can acquire objects before any JS reference mirrors them.
|
|
129
|
+
await session.options.native?.dispose(id);
|
|
130
|
+
session.kernel.command(KernelOp.Disposed, { object: id });
|
|
131
|
+
this.flush();
|
|
132
|
+
return;
|
|
133
|
+
}
|
|
134
|
+
object.disposing ??= (async () => {
|
|
135
|
+
const errors: unknown[] = [];
|
|
136
|
+
await object.activation.catch(() => {});
|
|
137
|
+
const scopes = session.kernel.command<number[]>(KernelOp.ScopesForOwner, {
|
|
138
|
+
owner: { kind: OwnerKind.Object, id },
|
|
139
|
+
});
|
|
140
|
+
try {
|
|
141
|
+
await session.programs.cleanupScopes(scopes);
|
|
142
|
+
} catch (error) {
|
|
143
|
+
errors.push(error);
|
|
144
|
+
}
|
|
145
|
+
try {
|
|
146
|
+
if (session.options.native?.hasOrb(object.orb)) await session.options.native.dispose(id);
|
|
147
|
+
} catch (error) {
|
|
148
|
+
errors.push(error);
|
|
149
|
+
}
|
|
150
|
+
object.binding?.close();
|
|
151
|
+
session.kernel.command(KernelOp.Disposed, { object: id });
|
|
152
|
+
session.objects.delete(id);
|
|
153
|
+
this.flush();
|
|
154
|
+
if (errors.length) throw new AggregateError(errors, "Object cleanup failed");
|
|
155
|
+
})();
|
|
156
|
+
return object.disposing;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** Keep one timer for the kernel's earliest deadline. */
|
|
160
|
+
private scheduleLinger(known?: number | null): void {
|
|
161
|
+
const session = this.session;
|
|
162
|
+
if (session.closing) return;
|
|
163
|
+
const deadline =
|
|
164
|
+
(known === undefined
|
|
165
|
+
? session.kernel.command<number | null>(KernelOp.NextDeadline)
|
|
166
|
+
: known) ?? undefined;
|
|
167
|
+
if (deadline === this.#lingerDeadline) return;
|
|
168
|
+
if (this.#linger !== undefined) clearTimeout(this.#linger);
|
|
169
|
+
this.#linger = undefined;
|
|
170
|
+
this.#lingerDeadline = deadline;
|
|
171
|
+
if (deadline === undefined) return;
|
|
172
|
+
this.#linger = setTimeout(
|
|
173
|
+
() => {
|
|
174
|
+
if (this.#lingerDeadline !== deadline) return;
|
|
175
|
+
this.#linger = undefined;
|
|
176
|
+
this.#lingerDeadline = undefined;
|
|
177
|
+
session.kernel.command(KernelOp.Tick, { now: session.now() });
|
|
178
|
+
this.flush();
|
|
179
|
+
},
|
|
180
|
+
Math.max(0, deadline - session.now()),
|
|
181
|
+
);
|
|
182
|
+
this.#linger.unref?.();
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** Combine kernel counts with retained JS values and jobs. */
|
|
186
|
+
diagnostics(): Diagnostics & { values: number; pendingJobs: number } {
|
|
187
|
+
const session = this.session;
|
|
188
|
+
if (this.#finalDiagnostics) return this.#finalDiagnostics;
|
|
189
|
+
return {
|
|
190
|
+
...session.kernel.command<Diagnostics>(KernelOp.Diagnostics),
|
|
191
|
+
values: session.values.size,
|
|
192
|
+
pendingJobs: session.jobs.size,
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/** Wait for physical cleanup before releasing the platform binding. */
|
|
197
|
+
close(): Promise<void> {
|
|
198
|
+
const session = this.session;
|
|
199
|
+
this.#closed ??= (async () => {
|
|
200
|
+
session.closing = true;
|
|
201
|
+
clearTimeout(this.#linger);
|
|
202
|
+
this.#linger = undefined;
|
|
203
|
+
this.#lingerDeadline = undefined;
|
|
204
|
+
session.kernel.command(KernelOp.Close);
|
|
205
|
+
await session.replacements.cancel();
|
|
206
|
+
this.flush();
|
|
207
|
+
for (;;) {
|
|
208
|
+
await session.options.native?.settled?.();
|
|
209
|
+
this.flush();
|
|
210
|
+
const pending = [...session.jobs];
|
|
211
|
+
if (!pending.length) break;
|
|
212
|
+
await Promise.allSettled(pending);
|
|
213
|
+
this.flush();
|
|
214
|
+
}
|
|
215
|
+
session.kernel.command(KernelOp.FinishClose);
|
|
216
|
+
session.values.clear();
|
|
217
|
+
session.handles.clear();
|
|
218
|
+
session.orbs.records.clear();
|
|
219
|
+
session.scopes.clear();
|
|
220
|
+
this.#finalDiagnostics = this.diagnostics();
|
|
221
|
+
session.kernel.port.free?.();
|
|
222
|
+
if (session.cleanupErrors.length)
|
|
223
|
+
throw new AggregateError(session.cleanupErrors, "Host cleanup failed");
|
|
224
|
+
})();
|
|
225
|
+
return this.#closed;
|
|
226
|
+
}
|
|
227
|
+
}
|
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
import { Declaration } from "../authoring/declaration.ts";
|
|
2
|
+
import { orb } from "../authoring/orb.ts";
|
|
3
|
+
import type { ContributionHandler, OrbDefinition, Participant } from "../authoring/types.ts";
|
|
4
|
+
import { Lifetime } from "../bridge/identifiers.ts";
|
|
5
|
+
import type { HookObservation, KernelOrb, Reload } from "../bridge/kernel.ts";
|
|
6
|
+
import { EnvironmentPhase, KernelOp, OwnerKind } from "../bridge/protocol.ts";
|
|
7
|
+
import { refuse, TembraError } from "../error.ts";
|
|
8
|
+
import { Errors } from "../errors.ts";
|
|
9
|
+
import { Context, context as checkedContext, issuedContext } from "./context.ts";
|
|
10
|
+
import type { Environment, OrbRecord } from "./records.ts";
|
|
11
|
+
import type { Session } from "./session.ts";
|
|
12
|
+
|
|
13
|
+
export class Orbs {
|
|
14
|
+
readonly records = new Map<number, OrbRecord>();
|
|
15
|
+
readonly operations = new Map<number, { orb: OrbRecord; handler: ContributionHandler }>();
|
|
16
|
+
#ready = new Map<number, Promise<void>>();
|
|
17
|
+
#ordinals = new Map<string, number>();
|
|
18
|
+
|
|
19
|
+
/** Retain local implementations and contribution callbacks. */
|
|
20
|
+
constructor(readonly session: Session) {}
|
|
21
|
+
|
|
22
|
+
/** Capture definitions and encode their kernel-owned contracts. */
|
|
23
|
+
declarations(definitions: readonly OrbDefinition[]): {
|
|
24
|
+
definitions: OrbDefinition[];
|
|
25
|
+
metadata: unknown[];
|
|
26
|
+
} {
|
|
27
|
+
const captured = definitions.map((definition) => orb(definition));
|
|
28
|
+
const current = this.session.kernel.command<KernelOrb[]>(KernelOp.Orbs);
|
|
29
|
+
const lookup = (name: string) => captured.find((f) => f.name === name);
|
|
30
|
+
const metadata = captured.map((definition) => {
|
|
31
|
+
if (
|
|
32
|
+
!this.session.kernel.features.views &&
|
|
33
|
+
Object.values(definition.services ?? {}).some((service) => service.access)
|
|
34
|
+
)
|
|
35
|
+
throw new TembraError(Errors.Unsupported.Views);
|
|
36
|
+
const requires = Object.entries(definition.requires ?? {}).map(([alias, requirement]) => {
|
|
37
|
+
const name = requirement.orb ?? alias;
|
|
38
|
+
const provider = lookup(name);
|
|
39
|
+
const info = current.find((f) => f.name === name);
|
|
40
|
+
const names = provider
|
|
41
|
+
? Object.keys(provider.services ?? {})
|
|
42
|
+
: (info?.services.map((s) => s.name) ?? []);
|
|
43
|
+
const service = names.includes(alias) ? alias : names.length === 1 ? names[0] : undefined;
|
|
44
|
+
if (requirement.methods && !service)
|
|
45
|
+
refuse(Errors.Invalid.DependencyService, `Use explicit services for ${name}`);
|
|
46
|
+
return {
|
|
47
|
+
orb: name,
|
|
48
|
+
apiVersion: requirement.apiVersion,
|
|
49
|
+
services:
|
|
50
|
+
requirement.services ??
|
|
51
|
+
(requirement.methods ? { [service!]: requirement.methods } : {}),
|
|
52
|
+
hooks: requirement.hooks ?? [],
|
|
53
|
+
};
|
|
54
|
+
});
|
|
55
|
+
for (const [alias, hooks] of Object.entries(definition.contributes ?? {})) {
|
|
56
|
+
const requirement = definition.requires?.[alias];
|
|
57
|
+
if (!requirement) refuse(Errors.Invalid.HookDependency, alias);
|
|
58
|
+
for (const [hook, contribution] of Object.entries(hooks)) {
|
|
59
|
+
if (!requirement.hooks?.includes(hook)) refuse(Errors.Invalid.HookDependency, hook);
|
|
60
|
+
const priority = typeof contribution === "function" ? 0 : (contribution.priority ?? 0);
|
|
61
|
+
if (!Number.isInteger(priority) || priority < -0x8000_0000 || priority > 0x7fff_ffff)
|
|
62
|
+
refuse(Errors.Invalid.Priority);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return {
|
|
66
|
+
name: definition.name,
|
|
67
|
+
apiVersion: definition.apiVersion,
|
|
68
|
+
requires,
|
|
69
|
+
hooks: Object.keys(definition.hooks ?? {}),
|
|
70
|
+
services: Object.entries(definition.services ?? {}).map(([name, service]) => ({
|
|
71
|
+
name,
|
|
72
|
+
methods: Object.keys(service.methods),
|
|
73
|
+
lifetime: service.lifetime ?? Lifetime.Referenced,
|
|
74
|
+
linger: service.linger ?? 0,
|
|
75
|
+
})),
|
|
76
|
+
};
|
|
77
|
+
});
|
|
78
|
+
return { definitions: captured, metadata };
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Commit new orb metadata before opening its scopes. */
|
|
82
|
+
async install(definitions: readonly OrbDefinition[]): Promise<void> {
|
|
83
|
+
const current = this.session.kernel.command<KernelOrb[]>(KernelOp.Orbs);
|
|
84
|
+
if (definitions.some((f) => current.some((installed) => installed.name === f.name)))
|
|
85
|
+
refuse(Errors.Invalid.OrbInstalled, "Use reload to replace an installed orb");
|
|
86
|
+
const prepared = this.declarations(definitions);
|
|
87
|
+
const reload = this.session.kernel.command<Reload>(KernelOp.Prepare, {
|
|
88
|
+
orbs: prepared.metadata,
|
|
89
|
+
});
|
|
90
|
+
this.session.kernel.command(KernelOp.Commit, { ticket: reload.id });
|
|
91
|
+
const records = reload.orbs.map((info) => ({
|
|
92
|
+
info,
|
|
93
|
+
definition: prepared.definitions.find((f) => f.name === info.name)!,
|
|
94
|
+
}));
|
|
95
|
+
for (const record of records) this.records.set(record.info.id, record);
|
|
96
|
+
for (const record of records) this.registerContributions(record);
|
|
97
|
+
await Promise.all(records.map((record) => this.ready(record)));
|
|
98
|
+
for (const record of records) {
|
|
99
|
+
for (const service of record.info.services.filter((s) => s.lifetime === Lifetime.Host)) {
|
|
100
|
+
const reference = await this.session.handles.get(service.name, "main", {
|
|
101
|
+
principal: "host",
|
|
102
|
+
});
|
|
103
|
+
reference.release();
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
this.session.lifecycle.flush();
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Declare one shared scope for this orb version. */
|
|
110
|
+
scope(record: OrbRecord): Environment {
|
|
111
|
+
if (record.scope) return record.scope;
|
|
112
|
+
const environment = this.session.scopes.environment(
|
|
113
|
+
{ kind: OwnerKind.Orb, id: record.info.owner },
|
|
114
|
+
record,
|
|
115
|
+
);
|
|
116
|
+
record.scope = environment;
|
|
117
|
+
try {
|
|
118
|
+
const value = record.definition.create?.(new Declaration(this.session, environment)) ?? {};
|
|
119
|
+
if (value && typeof (value as { then?: unknown }).then === "function")
|
|
120
|
+
refuse(Errors.Invalid.AsyncFactory);
|
|
121
|
+
environment.value = value;
|
|
122
|
+
} finally {
|
|
123
|
+
environment.phase = EnvironmentPhase.Prepared;
|
|
124
|
+
this.session.programs.register(environment);
|
|
125
|
+
}
|
|
126
|
+
return environment;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** Share pending activation and clean up failed orb scopes. */
|
|
130
|
+
ready(record: OrbRecord): Promise<void> {
|
|
131
|
+
if (record.scope?.phase === EnvironmentPhase.Live) return Promise.resolve();
|
|
132
|
+
let ready = this.#ready.get(record.info.id);
|
|
133
|
+
if (!ready) {
|
|
134
|
+
ready = (async () => {
|
|
135
|
+
try {
|
|
136
|
+
await this.session.scopes.readyHostScope();
|
|
137
|
+
if (record.scope?.phase === EnvironmentPhase.Closed) delete record.scope;
|
|
138
|
+
const scope = this.scope(record);
|
|
139
|
+
await this.session.programs.activate(scope.id);
|
|
140
|
+
} catch (error) {
|
|
141
|
+
if (record.scope) {
|
|
142
|
+
await this.session.programs.cleanup([record.scope]);
|
|
143
|
+
delete record.scope;
|
|
144
|
+
}
|
|
145
|
+
throw error;
|
|
146
|
+
}
|
|
147
|
+
})();
|
|
148
|
+
this.#ready.set(record.info.id, ready);
|
|
149
|
+
const clear = () => {
|
|
150
|
+
if (this.#ready.get(record.info.id) === ready) this.#ready.delete(record.info.id);
|
|
151
|
+
};
|
|
152
|
+
ready.then(clear, clear);
|
|
153
|
+
}
|
|
154
|
+
return ready;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** Register callback identities with stable contribution order. */
|
|
158
|
+
registerContributions(record: OrbRecord): void {
|
|
159
|
+
for (const [alias, hooks] of Object.entries(record.definition.contributes ?? {})) {
|
|
160
|
+
const requirement = record.definition.requires![alias]!;
|
|
161
|
+
const target = requirement.orb ?? alias;
|
|
162
|
+
for (const [hook, contribution] of Object.entries(hooks)) {
|
|
163
|
+
const operation = this.session.kernel.command<number>(KernelOp.Allocate);
|
|
164
|
+
const key = JSON.stringify([record.info.name, target, hook]);
|
|
165
|
+
if (!this.#ordinals.has(key))
|
|
166
|
+
this.#ordinals.set(
|
|
167
|
+
key,
|
|
168
|
+
this.session.kernel.command<number>(KernelOp.ContributionOrdinal),
|
|
169
|
+
);
|
|
170
|
+
this.operations.set(operation, {
|
|
171
|
+
orb: record,
|
|
172
|
+
handler: typeof contribution === "function" ? contribution : contribution.handle,
|
|
173
|
+
});
|
|
174
|
+
this.session.kernel.command(KernelOp.Contribute, {
|
|
175
|
+
orb: record.info.id,
|
|
176
|
+
target,
|
|
177
|
+
hook,
|
|
178
|
+
operation,
|
|
179
|
+
priority: typeof contribution === "function" ? 0 : (contribution.priority ?? 0),
|
|
180
|
+
ordinal: this.#ordinals.get(key),
|
|
181
|
+
});
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** Validate the caller and execute the kernel's admitted hook plan. */
|
|
187
|
+
async runHook(
|
|
188
|
+
environment: Environment,
|
|
189
|
+
name: string,
|
|
190
|
+
context: Context,
|
|
191
|
+
input: unknown,
|
|
192
|
+
): Promise<unknown> {
|
|
193
|
+
context = checkedContext(context, this.session);
|
|
194
|
+
const definition = environment.orb.definition.hooks?.[name];
|
|
195
|
+
if (!definition) refuse(Errors.Invalid.Hook, name);
|
|
196
|
+
const plan = this.session.kernel.command<number[]>(KernelOp.HookPlan, {
|
|
197
|
+
root: context.root,
|
|
198
|
+
target: environment.orb.info.name,
|
|
199
|
+
hook: name,
|
|
200
|
+
});
|
|
201
|
+
const participants: Participant[] = plan.map((operation) => async (ctx, input, next) => {
|
|
202
|
+
return this.runContribution(operation, ctx, input, next);
|
|
203
|
+
});
|
|
204
|
+
return definition.run(context, input, participants);
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Await the kernel's single owner-bound hook observation, including after cancellation.
|
|
208
|
+
* The observation starts with an empty metadata frame. It does not revive the source context.
|
|
209
|
+
* Host/owner cleanup can cancel it; physical work remains tracked until it settles.
|
|
210
|
+
*/
|
|
211
|
+
async observe(
|
|
212
|
+
environment: Environment,
|
|
213
|
+
name: string,
|
|
214
|
+
operation: number,
|
|
215
|
+
source: Context,
|
|
216
|
+
input: unknown,
|
|
217
|
+
): Promise<void> {
|
|
218
|
+
source = issuedContext(source, this.session);
|
|
219
|
+
const definition = environment.orb.definition.hooks?.[name];
|
|
220
|
+
if (!definition) refuse(Errors.Invalid.Hook, name);
|
|
221
|
+
if (!source.invocation) throw new TembraError(Errors.Forbidden.ObservationSource);
|
|
222
|
+
const admitted = this.session.kernel.command<HookObservation>(KernelOp.BeginHookObservation, {
|
|
223
|
+
source: source.invocation.id,
|
|
224
|
+
orb: environment.orb.info.id,
|
|
225
|
+
operation,
|
|
226
|
+
...(environment.object ? { object: environment.object.id } : {}),
|
|
227
|
+
hook: name,
|
|
228
|
+
});
|
|
229
|
+
await this.session.track(
|
|
230
|
+
this.session.calls.root(
|
|
231
|
+
async () => {
|
|
232
|
+
try {
|
|
233
|
+
const context = new Context(
|
|
234
|
+
this.session,
|
|
235
|
+
admitted.invocation.root,
|
|
236
|
+
admitted.invocation,
|
|
237
|
+
);
|
|
238
|
+
const participants: Participant[] = admitted.plan.map(
|
|
239
|
+
(operation) => async (ctx, input, next) =>
|
|
240
|
+
this.runContribution(operation, ctx, input, next),
|
|
241
|
+
);
|
|
242
|
+
await definition.run(context, input, participants);
|
|
243
|
+
} finally {
|
|
244
|
+
this.session.lifecycle.finishCall(admitted.invocation.id);
|
|
245
|
+
}
|
|
246
|
+
},
|
|
247
|
+
false,
|
|
248
|
+
admitted.invocation.root,
|
|
249
|
+
),
|
|
250
|
+
);
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** Execute a participant from either adapter under its own managed orb invocation. */
|
|
254
|
+
async runContribution(
|
|
255
|
+
operation: number,
|
|
256
|
+
ctx: Context,
|
|
257
|
+
input: unknown,
|
|
258
|
+
next?: (input: unknown) => Promise<unknown>,
|
|
259
|
+
): Promise<unknown> {
|
|
260
|
+
ctx = checkedContext(ctx, this.session);
|
|
261
|
+
const contributor = this.operations.get(operation);
|
|
262
|
+
if (!contributor) {
|
|
263
|
+
const native = this.session.options.native;
|
|
264
|
+
if (native?.hasContribution?.(operation) && native.contribute)
|
|
265
|
+
return native.contribute(operation, ctx, input);
|
|
266
|
+
throw new TembraError(Errors.Gone.Contribution);
|
|
267
|
+
}
|
|
268
|
+
const scope = contributor.orb.scope;
|
|
269
|
+
if (!scope) throw new TembraError(Errors.Unavailable.OrbScope);
|
|
270
|
+
return this.session.calls.owned(
|
|
271
|
+
scope,
|
|
272
|
+
operation,
|
|
273
|
+
(entered) => contributor.handler(entered, input, next),
|
|
274
|
+
ctx,
|
|
275
|
+
);
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Clean up a retired version before removing its callbacks. */
|
|
279
|
+
retire(id: number): void {
|
|
280
|
+
const scopes = this.session.kernel.command<number[]>(KernelOp.ScopesForOrb, { orb: id });
|
|
281
|
+
const cleanup = this.session.programs.cleanupScopes(scopes);
|
|
282
|
+
this.session.track(
|
|
283
|
+
cleanup.then(() => {
|
|
284
|
+
for (const [operation, contribution] of this.operations)
|
|
285
|
+
if (contribution.orb.info.id === id) this.operations.delete(operation);
|
|
286
|
+
this.records.delete(id);
|
|
287
|
+
this.#ready.delete(id);
|
|
288
|
+
}),
|
|
289
|
+
true,
|
|
290
|
+
);
|
|
291
|
+
}
|
|
292
|
+
}
|