@syntropika/tembra-sdk 0.1.0 → 0.2.1

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/dist/host.js CHANGED
@@ -348,6 +348,41 @@ function refuse(error, message = error.message) {
348
348
  throw new TembraError(error, message);
349
349
  }
350
350
 
351
+ // src/authoring/service-identities.ts
352
+ var identityKey = Symbol.for("@syntropika/tembra-sdk/service-identities");
353
+ var existing = Object.getOwnPropertyDescriptor(globalThis, identityKey)?.value;
354
+ if (existing !== undefined && !(existing instanceof WeakMap))
355
+ throw new TypeError("The SDK service identity slot must contain a WeakMap");
356
+ var serviceIdentities = existing instanceof WeakMap ? existing : new WeakMap;
357
+ if (existing === undefined)
358
+ Object.defineProperty(globalThis, identityKey, { value: serviceIdentities });
359
+
360
+ // src/authoring/services.ts
361
+ function associateServices(orb, apiVersion, services) {
362
+ const pending = new Map;
363
+ for (const [name, original, captured] of services) {
364
+ const identity = { orb, name, apiVersion };
365
+ for (const definition of [original, captured]) {
366
+ const previous = pending.get(definition) ?? serviceIdentities.get(definition);
367
+ if (previous && (previous.orb !== orb || previous.name !== name || previous.apiVersion !== apiVersion))
368
+ refuse(Errors.Invalid.Service, "A service definition must have one orb, name and API version");
369
+ pending.set(definition, identity);
370
+ }
371
+ }
372
+ for (const [definition, identity] of pending)
373
+ serviceIdentities.set(definition, identity);
374
+ }
375
+ function serviceAcquisition(service, options = {}) {
376
+ if (typeof service === "string")
377
+ return { name: service, options };
378
+ const identity = serviceIdentities.get(service);
379
+ if (!identity)
380
+ refuse(Errors.Invalid.Service, "Declare this service in an orb before acquiring it");
381
+ if (options.apiVersion !== undefined && options.apiVersion !== identity.apiVersion)
382
+ refuse(Errors.Invalid.Service, "The acquisition API version must match the service declaration");
383
+ return { name: identity.name, options: { ...options, apiVersion: identity.apiVersion } };
384
+ }
385
+
351
386
  // src/authoring/orb.ts
352
387
  function orb(definition) {
353
388
  if (!definition.name || !Number.isInteger(definition.apiVersion) || definition.apiVersion <= 0)
@@ -396,13 +431,19 @@ function orb(definition) {
396
431
  typeof contribution === "function" ? contribution : Object.freeze({ ...contribution })
397
432
  ])))
398
433
  ]));
399
- return Object.freeze({
434
+ const captured = Object.freeze({
400
435
  ...definition,
401
436
  services: Object.freeze(services),
402
437
  requires: Object.freeze(requires),
403
438
  hooks: Object.freeze(hooks),
404
439
  contributes: Object.freeze(contributes)
405
440
  });
441
+ associateServices(definition.name, definition.apiVersion, Object.entries(definition.services ?? {}).map(([name, original]) => [
442
+ name,
443
+ original,
444
+ services[name]
445
+ ]));
446
+ return captured;
406
447
  }
407
448
 
408
449
  // src/bridge/protocol.ts
@@ -929,20 +970,24 @@ class Declaration {
929
970
  }
930
971
  get(service, key, options = {}) {
931
972
  this.check();
932
- const requirement = this.session.scopes.requirement(this.environment, service);
973
+ const acquisition = serviceAcquisition(service, options);
974
+ const requirement = this.session.scopes.requirement(this.environment, acquisition.name);
933
975
  const resolved = requirement.service;
976
+ if (typeof service !== "string" && resolved !== acquisition.name)
977
+ refuse(Errors.Invalid.Service, "A typed dependency must resolve its declared service name");
934
978
  if (!this.environment.object && this.environment.orb.definition.services?.[resolved])
935
979
  refuse(Errors.Invalid.DependencyCycle);
936
- const identity = JSON.stringify([resolved, key, options.principal ?? this.principal]);
937
- const existing = this.environment.dependencies.get(identity);
938
- if (existing)
939
- return existing;
940
- const reference = this.session.handles.hold(resolved, key, {
980
+ const admitted = serviceAcquisition(service, {
941
981
  ...options,
942
982
  ...requirement.apiVersion ? { apiVersion: requirement.apiVersion } : {},
943
983
  ...requirement.methods ? { methods: requirement.methods } : {},
944
984
  principal: options.principal ?? this.principal
945
985
  });
986
+ const identity = JSON.stringify([resolved, key, options.principal ?? this.principal]);
987
+ const existing = this.environment.dependencies.get(identity);
988
+ if (existing)
989
+ return existing;
990
+ const reference = this.session.handles.hold(resolved, key, admitted.options);
946
991
  if (this.environment.object) {
947
992
  try {
948
993
  this.session.kernel.command(KernelOp.Dependency, {
@@ -2311,7 +2356,15 @@ class References {
2311
2356
  owned.add(record);
2312
2357
  return object.activation;
2313
2358
  }
2314
- hold(service, key, options = {}, ctx) {
2359
+ hold(definition, key, options = {}, ctx) {
2360
+ let service;
2361
+ if (typeof definition === "string")
2362
+ service = definition;
2363
+ else {
2364
+ const acquisition = serviceAcquisition(definition, options);
2365
+ service = acquisition.name;
2366
+ options = acquisition.options;
2367
+ }
2315
2368
  const session = this.session;
2316
2369
  if (ctx)
2317
2370
  context(ctx, session);
package/dist/index.js CHANGED
@@ -333,6 +333,31 @@ function refuse(error, message = error.message) {
333
333
  throw new TembraError(error, message);
334
334
  }
335
335
 
336
+ // src/authoring/service-identities.ts
337
+ var identityKey = Symbol.for("@syntropika/tembra-sdk/service-identities");
338
+ var existing = Object.getOwnPropertyDescriptor(globalThis, identityKey)?.value;
339
+ if (existing !== undefined && !(existing instanceof WeakMap))
340
+ throw new TypeError("The SDK service identity slot must contain a WeakMap");
341
+ var serviceIdentities = existing instanceof WeakMap ? existing : new WeakMap;
342
+ if (existing === undefined)
343
+ Object.defineProperty(globalThis, identityKey, { value: serviceIdentities });
344
+
345
+ // src/authoring/services.ts
346
+ function associateServices(orb, apiVersion, services) {
347
+ const pending = new Map;
348
+ for (const [name, original, captured] of services) {
349
+ const identity = { orb, name, apiVersion };
350
+ for (const definition of [original, captured]) {
351
+ const previous = pending.get(definition) ?? serviceIdentities.get(definition);
352
+ if (previous && (previous.orb !== orb || previous.name !== name || previous.apiVersion !== apiVersion))
353
+ refuse(Errors.Invalid.Service, "A service definition must have one orb, name and API version");
354
+ pending.set(definition, identity);
355
+ }
356
+ }
357
+ for (const [definition, identity] of pending)
358
+ serviceIdentities.set(definition, identity);
359
+ }
360
+
336
361
  // src/authoring/orb.ts
337
362
  function orb(definition) {
338
363
  if (!definition.name || !Number.isInteger(definition.apiVersion) || definition.apiVersion <= 0)
@@ -381,13 +406,19 @@ function orb(definition) {
381
406
  typeof contribution === "function" ? contribution : Object.freeze({ ...contribution })
382
407
  ])))
383
408
  ]));
384
- return Object.freeze({
409
+ const captured = Object.freeze({
385
410
  ...definition,
386
411
  services: Object.freeze(services),
387
412
  requires: Object.freeze(requires),
388
413
  hooks: Object.freeze(hooks),
389
414
  contributes: Object.freeze(contributes)
390
415
  });
416
+ associateServices(definition.name, definition.apiVersion, Object.entries(definition.services ?? {}).map(([name, original]) => [
417
+ name,
418
+ original,
419
+ services[name]
420
+ ]));
421
+ return captured;
391
422
  }
392
423
  // src/authoring/hooks.ts
393
424
  function series() {
@@ -7,8 +7,11 @@ export interface Transport {
7
7
  send(frame: Uint8Array): void | Promise<void>;
8
8
  /** Register frame and connection callbacks until detached. */
9
9
  listen(receive: (frame: Uint8Array) => void, closed: (error?: unknown) => void): () => void;
10
- /** Close the underlying connection. */
11
- close(): void;
10
+ /**
11
+ * Close after channel listeners detach, handling or ignoring the supplied terminal cause.
12
+ * Wrap platform methods; do not forward this cause to WebSocket.close(code), destroy(error), or end.
13
+ */
14
+ close(cause?: unknown): void;
12
15
  }
13
16
  export interface Limits {
14
17
  codec?: Codec;
package/dist/node.js CHANGED
@@ -353,6 +353,41 @@ function refuse(error, message = error.message) {
353
353
  throw new TembraError(error, message);
354
354
  }
355
355
 
356
+ // src/authoring/service-identities.ts
357
+ var identityKey = Symbol.for("@syntropika/tembra-sdk/service-identities");
358
+ var existing = Object.getOwnPropertyDescriptor(globalThis, identityKey)?.value;
359
+ if (existing !== undefined && !(existing instanceof WeakMap))
360
+ throw new TypeError("The SDK service identity slot must contain a WeakMap");
361
+ var serviceIdentities = existing instanceof WeakMap ? existing : new WeakMap;
362
+ if (existing === undefined)
363
+ Object.defineProperty(globalThis, identityKey, { value: serviceIdentities });
364
+
365
+ // src/authoring/services.ts
366
+ function associateServices(orb, apiVersion, services) {
367
+ const pending = new Map;
368
+ for (const [name, original, captured] of services) {
369
+ const identity = { orb, name, apiVersion };
370
+ for (const definition of [original, captured]) {
371
+ const previous = pending.get(definition) ?? serviceIdentities.get(definition);
372
+ if (previous && (previous.orb !== orb || previous.name !== name || previous.apiVersion !== apiVersion))
373
+ refuse(Errors.Invalid.Service, "A service definition must have one orb, name and API version");
374
+ pending.set(definition, identity);
375
+ }
376
+ }
377
+ for (const [definition, identity] of pending)
378
+ serviceIdentities.set(definition, identity);
379
+ }
380
+ function serviceAcquisition(service, options = {}) {
381
+ if (typeof service === "string")
382
+ return { name: service, options };
383
+ const identity = serviceIdentities.get(service);
384
+ if (!identity)
385
+ refuse(Errors.Invalid.Service, "Declare this service in an orb before acquiring it");
386
+ if (options.apiVersion !== undefined && options.apiVersion !== identity.apiVersion)
387
+ refuse(Errors.Invalid.Service, "The acquisition API version must match the service declaration");
388
+ return { name: identity.name, options: { ...options, apiVersion: identity.apiVersion } };
389
+ }
390
+
356
391
  // src/authoring/orb.ts
357
392
  function orb(definition) {
358
393
  if (!definition.name || !Number.isInteger(definition.apiVersion) || definition.apiVersion <= 0)
@@ -401,13 +436,19 @@ function orb(definition) {
401
436
  typeof contribution === "function" ? contribution : Object.freeze({ ...contribution })
402
437
  ])))
403
438
  ]));
404
- return Object.freeze({
439
+ const captured = Object.freeze({
405
440
  ...definition,
406
441
  services: Object.freeze(services),
407
442
  requires: Object.freeze(requires),
408
443
  hooks: Object.freeze(hooks),
409
444
  contributes: Object.freeze(contributes)
410
445
  });
446
+ associateServices(definition.name, definition.apiVersion, Object.entries(definition.services ?? {}).map(([name, original]) => [
447
+ name,
448
+ original,
449
+ services[name]
450
+ ]));
451
+ return captured;
411
452
  }
412
453
 
413
454
  // src/bridge/protocol.ts
@@ -934,20 +975,24 @@ class Declaration {
934
975
  }
935
976
  get(service, key, options = {}) {
936
977
  this.check();
937
- const requirement = this.session.scopes.requirement(this.environment, service);
978
+ const acquisition = serviceAcquisition(service, options);
979
+ const requirement = this.session.scopes.requirement(this.environment, acquisition.name);
938
980
  const resolved = requirement.service;
981
+ if (typeof service !== "string" && resolved !== acquisition.name)
982
+ refuse(Errors.Invalid.Service, "A typed dependency must resolve its declared service name");
939
983
  if (!this.environment.object && this.environment.orb.definition.services?.[resolved])
940
984
  refuse(Errors.Invalid.DependencyCycle);
941
- const identity = JSON.stringify([resolved, key, options.principal ?? this.principal]);
942
- const existing = this.environment.dependencies.get(identity);
943
- if (existing)
944
- return existing;
945
- const reference = this.session.handles.hold(resolved, key, {
985
+ const admitted = serviceAcquisition(service, {
946
986
  ...options,
947
987
  ...requirement.apiVersion ? { apiVersion: requirement.apiVersion } : {},
948
988
  ...requirement.methods ? { methods: requirement.methods } : {},
949
989
  principal: options.principal ?? this.principal
950
990
  });
991
+ const identity = JSON.stringify([resolved, key, options.principal ?? this.principal]);
992
+ const existing = this.environment.dependencies.get(identity);
993
+ if (existing)
994
+ return existing;
995
+ const reference = this.session.handles.hold(resolved, key, admitted.options);
951
996
  if (this.environment.object) {
952
997
  try {
953
998
  this.session.kernel.command(KernelOp.Dependency, {
@@ -2354,7 +2399,15 @@ class References {
2354
2399
  owned.add(record);
2355
2400
  return object.activation;
2356
2401
  }
2357
- hold(service, key, options = {}, ctx) {
2402
+ hold(definition, key, options = {}, ctx) {
2403
+ let service;
2404
+ if (typeof definition === "string")
2405
+ service = definition;
2406
+ else {
2407
+ const acquisition = serviceAcquisition(definition, options);
2408
+ service = acquisition.name;
2409
+ options = acquisition.options;
2410
+ }
2358
2411
  const session = this.session;
2359
2412
  if (ctx)
2360
2413
  context(ctx, session);
package/dist/rpc.js CHANGED
@@ -659,11 +659,16 @@ class Channel {
659
659
  throw new TembraError(Errors.Invalid.RpcFrame);
660
660
  receive(message);
661
661
  } catch (error) {
662
- options.onError?.(error);
662
+ this.#report(error);
663
663
  this.close(error);
664
664
  }
665
665
  }, (error) => this.close(error));
666
666
  }
667
+ #report(error) {
668
+ try {
669
+ this.options.onError?.(error);
670
+ } catch {}
671
+ }
667
672
  async send(message) {
668
673
  if (this.closed)
669
674
  throw new TembraError(Errors.Gone.Connection);
@@ -676,9 +681,18 @@ class Channel {
676
681
  if (this.closed)
677
682
  return;
678
683
  this.closed = true;
679
- this.#detach?.();
680
- this.transport.close();
681
- this.ended(error);
684
+ try {
685
+ this.#detach?.();
686
+ } catch (detachError) {
687
+ this.#report(detachError);
688
+ }
689
+ try {
690
+ this.transport.close(error);
691
+ } catch (closeError) {
692
+ this.#report(closeError);
693
+ } finally {
694
+ this.ended(error);
695
+ }
682
696
  }
683
697
  }
684
698
 
@@ -799,7 +813,10 @@ class RemoteHost {
799
813
  this.#states.clear();
800
814
  });
801
815
  }
802
- async request(op, payload, signal) {
816
+ request(op, payload, signal) {
817
+ return this.#request(op, payload, signal);
818
+ }
819
+ async#request(op, payload, signal, received) {
803
820
  signal?.throwIfAborted();
804
821
  if (this.#pending.size >= this.channel.maxPending)
805
822
  throw new TembraError(Errors.Exhausted.PendingRequests);
@@ -808,14 +825,38 @@ class RemoteHost {
808
825
  throw new TembraError(Errors.Exhausted.RequestIds);
809
826
  let abort;
810
827
  const result = new Promise((resolve, reject) => {
811
- this.#pending.set(id, { resolve, reject });
828
+ const pending = {
829
+ resolve: (value) => {
830
+ try {
831
+ received?.(value);
832
+ resolve(value);
833
+ } catch (error) {
834
+ if (op === RpcOp.Get)
835
+ this.#release(value?.reference);
836
+ reject(error);
837
+ }
838
+ },
839
+ reject
840
+ };
841
+ this.#pending.set(id, pending);
812
842
  abort = () => {
813
- this.#pending.delete(id);
843
+ if (this.#pending.get(id) !== pending)
844
+ return;
845
+ if (op === RpcOp.Get) {
846
+ this.#pending.set(id, {
847
+ resolve: (value) => this.#release(value?.reference),
848
+ reject: () => {}
849
+ });
850
+ } else {
851
+ this.#pending.delete(id);
852
+ }
814
853
  reject(signal?.reason ?? new TembraError(Errors.Cancelled.Request));
815
854
  this.channel.send({ op: RpcOp.Cancel, payload: { id } }).catch(() => {});
816
855
  };
817
856
  signal?.addEventListener("abort", abort, { once: true });
818
857
  this.channel.send({ id, op, payload }).catch((error) => {
858
+ if (this.#pending.get(id) !== pending)
859
+ return;
819
860
  this.#pending.delete(id);
820
861
  reject(error);
821
862
  });
@@ -827,12 +868,19 @@ class RemoteHost {
827
868
  signal?.removeEventListener("abort", abort);
828
869
  }
829
870
  }
871
+ #release(reference) {
872
+ if (!Number.isSafeInteger(reference) || reference <= 0 || this.channel.closed)
873
+ return;
874
+ this.request(RpcOp.Release, { reference }).catch((error) => {
875
+ try {
876
+ this.channel.options.onError?.(error);
877
+ } catch {}
878
+ });
879
+ }
830
880
  installedOrbs() {
831
881
  return this.request(RpcOp.Describe, null);
832
882
  }
833
883
  async get(service, key, options = {}) {
834
- const acquired = await this.request(RpcOp.Get, { service, key: typeof key === "string" ? [key] : key }, options.signal);
835
- const id = acquired.reference;
836
884
  let released = false;
837
885
  const check = () => {
838
886
  if (released)
@@ -840,9 +888,16 @@ class RemoteHost {
840
888
  if (this.channel.closed)
841
889
  throw new TembraError(Errors.Gone.Connection);
842
890
  };
843
- const state = Object.hasOwn(acquired, "state") ? new RemoteState(acquired.state, check, (error) => this.channel.options.onError?.(error)) : undefined;
844
- if (state)
845
- this.#states.set(id, state);
891
+ let state;
892
+ const acquired = await this.#request(RpcOp.Get, { service, key: typeof key === "string" ? [key] : key }, options.signal, (value) => {
893
+ if (!value || !Number.isSafeInteger(value.reference) || value.reference <= 0 || !Array.isArray(value.methods) || !value.methods.every((method) => typeof method === "string"))
894
+ throw new TembraError(Errors.Invalid.RpcFrame);
895
+ if (Object.hasOwn(value, "state")) {
896
+ state = new RemoteState(value.state, check, (error) => this.channel.options.onError?.(error));
897
+ this.#states.set(value.reference, state);
898
+ }
899
+ });
900
+ const id = acquired.reference;
846
901
  const target = {
847
902
  ready: Promise.resolve(),
848
903
  get status() {
@@ -1,5 +1,5 @@
1
1
  import { ContextKey } from "../context-key.ts";
2
- import type { AcquisitionOptions, DynamicReference } from "../authoring/types.ts";
2
+ import type { AcquisitionOptions, DynamicReference, ServiceDefinition, ServiceReference } from "../authoring/types.ts";
3
3
  import type { Invocation } from "../bridge/kernel.ts";
4
4
  import type { Session } from "./session.ts";
5
5
  /** An issued operation scope. Keeping this object does not extend its root or invocation. */
@@ -25,6 +25,7 @@ export declare class Context {
25
25
  /** Cancel the root and dispatch its cancellation actions. */
26
26
  cancel(): void;
27
27
  /** Acquire a reference whose claim ends with this root. */
28
+ get<const Service extends ServiceDefinition>(service: Service, key: string | readonly string[], options?: AcquisitionOptions): Promise<ServiceReference<Service>>;
28
29
  get(service: string, key: string | readonly string[], options?: AcquisitionOptions): Promise<DynamicReference>;
29
30
  /** Read a named host resource while the context remains valid. */
30
31
  resource<T>(name: string): import("../authoring/types.ts").Resource<T>;
@@ -1,4 +1,4 @@
1
- import type { AcquisitionOptions, DynamicReference } from "../authoring/types.ts";
1
+ import type { AcquisitionOptions, DynamicReference, ServiceDefinition } from "../authoring/types.ts";
2
2
  import type { Acquisition } from "../bridge/kernel.ts";
3
3
  import { Context } from "./context.ts";
4
4
  import type { Address, OrbRecord, ObjectRecord, ReferenceRecord } from "./records.ts";
@@ -12,9 +12,9 @@ export declare class References {
12
12
  /** Activate an object reserved by the native facade in this shared kernel. */
13
13
  activateAcquired(acquired: Acquisition, address: Address, requiredMethods?: string[]): Promise<void>;
14
14
  /** Acquire ownership and create a local service handle. */
15
- hold(service: string, key: string | readonly string[], options?: AcquisitionOptions, ctx?: Context): DynamicReference;
15
+ hold(definition: string | ServiceDefinition, key: string | readonly string[], options?: AcquisitionOptions, ctx?: Context): DynamicReference;
16
16
  /** Release the acquired claim if activation fails. */
17
- get(service: string, key: string | readonly string[], options?: AcquisitionOptions, ctx?: Context): Promise<DynamicReference>;
17
+ get(service: string | ServiceDefinition, key: string | readonly string[], options?: AcquisitionOptions, ctx?: Context): Promise<DynamicReference>;
18
18
  /** Require a reference issued by this session. */
19
19
  reference(value: unknown): ReferenceRecord;
20
20
  /** Cache native orb metadata once per version. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syntropika/tembra-sdk",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "license": "Apache-2.0",
5
5
  "repository": {
6
6
  "type": "git",
@@ -89,8 +89,8 @@
89
89
  "access": "public"
90
90
  },
91
91
  "dependencies": {
92
- "@syntropika/tembra-engine-node": "0.1.0",
93
- "@syntropika/tembra-engine-wasm": "0.1.0",
92
+ "@syntropika/tembra-engine-node": "0.2.1",
93
+ "@syntropika/tembra-engine-wasm": "0.2.1",
94
94
  "enhanced-resolve": "5.26.0",
95
95
  "typescript": "5.9.3"
96
96
  },
@@ -7,6 +7,7 @@ import type { Environment } from "../runtime/records.ts";
7
7
  import type { Session } from "../runtime/session.ts";
8
8
  import type { Readable, State, StateOptions } from "../state.ts";
9
9
  import { StateBinding, validate } from "../state.ts";
10
+ import { serviceAcquisition } from "./services.ts";
10
11
  import type {
11
12
  AcquisitionOptions,
12
13
  Completion,
@@ -16,6 +17,8 @@ import type {
16
17
  Resource,
17
18
  ResourceOptions,
18
19
  TaskScope,
20
+ ServiceDefinition,
21
+ ServiceReference,
19
22
  } from "./types.ts";
20
23
 
21
24
  /** Available only during its synchronous factory pass. Issued handles remain usable afterwards. */
@@ -76,25 +79,39 @@ export class Declaration {
76
79
  }
77
80
 
78
81
  /** Orb factories cannot depend on their own services; object factories may use sibling services. */
82
+ get<const Service extends ServiceDefinition>(
83
+ service: Service,
84
+ key: string | readonly string[],
85
+ options?: AcquisitionOptions,
86
+ ): ServiceReference<Service>;
79
87
  get(
80
88
  service: string,
81
89
  key: string | readonly string[],
90
+ options?: AcquisitionOptions,
91
+ ): DynamicReference;
92
+ get(
93
+ service: string | ServiceDefinition,
94
+ key: string | readonly string[],
82
95
  options: AcquisitionOptions = {},
83
96
  ): DynamicReference {
84
97
  this.check();
85
- const requirement = this.session.scopes.requirement(this.environment, service);
98
+ const acquisition = serviceAcquisition(service, options);
99
+ const requirement = this.session.scopes.requirement(this.environment, acquisition.name);
86
100
  const resolved = requirement.service;
101
+ if (typeof service !== "string" && resolved !== acquisition.name)
102
+ refuse(Errors.Invalid.Service, "A typed dependency must resolve its declared service name");
87
103
  if (!this.environment.object && this.environment.orb.definition.services?.[resolved])
88
104
  refuse(Errors.Invalid.DependencyCycle);
89
- const identity = JSON.stringify([resolved, key, options.principal ?? this.principal]);
90
- const existing = this.environment.dependencies.get(identity);
91
- if (existing) return existing;
92
- const reference = this.session.handles.hold(resolved, key, {
105
+ const admitted = serviceAcquisition(service, {
93
106
  ...options,
94
107
  ...(requirement.apiVersion ? { apiVersion: requirement.apiVersion } : {}),
95
108
  ...(requirement.methods ? { methods: requirement.methods } : {}),
96
109
  principal: options.principal ?? this.principal,
97
110
  });
111
+ const identity = JSON.stringify([resolved, key, options.principal ?? this.principal]);
112
+ const existing = this.environment.dependencies.get(identity);
113
+ if (existing) return existing;
114
+ const reference = this.session.handles.hold(resolved, key, admitted.options);
98
115
  if (this.environment.object) {
99
116
  try {
100
117
  this.session.kernel.command(KernelOp.Dependency, {
@@ -1,6 +1,7 @@
1
1
  import { Errors } from "../errors.ts";
2
2
 
3
3
  import { refuse } from "../error.ts";
4
+ import { associateServices } from "./services.ts";
4
5
  import type { OrbDefinition, ServiceDefinition } from "./types.ts";
5
6
 
6
7
  /** Captures executable declarations. No structural schemas or generated contracts are required. */
@@ -67,11 +68,21 @@ export function orb<const F extends OrbDefinition>(definition: F): Readonly<F> {
67
68
  ),
68
69
  ]),
69
70
  );
70
- return Object.freeze({
71
+ const captured = Object.freeze({
71
72
  ...definition,
72
73
  services: Object.freeze(services),
73
74
  requires: Object.freeze(requires),
74
75
  hooks: Object.freeze(hooks),
75
76
  contributes: Object.freeze(contributes),
76
- }) as Readonly<F>;
77
+ });
78
+ associateServices(
79
+ definition.name,
80
+ definition.apiVersion,
81
+ Object.entries(definition.services ?? {}).map(([name, original]) => [
82
+ name,
83
+ original,
84
+ services[name]!,
85
+ ]),
86
+ );
87
+ return captured as Readonly<F>;
77
88
  }
@@ -0,0 +1,20 @@
1
+ import type { ServiceDefinition } from "./types.ts";
2
+
3
+ export interface ServiceIdentity {
4
+ readonly orb: string;
5
+ readonly name: string;
6
+ readonly apiVersion: number;
7
+ }
8
+
9
+ // Standalone orb bundles and public SDK entrypoints share metadata within one JavaScript realm.
10
+ // Weak keys retain neither removed implementations nor an additional object lifecycle.
11
+ const identityKey = Symbol.for("@syntropika/tembra-sdk/service-identities");
12
+ const existing: unknown = Object.getOwnPropertyDescriptor(globalThis, identityKey)?.value;
13
+ if (existing !== undefined && !(existing instanceof WeakMap))
14
+ throw new TypeError("The SDK service identity slot must contain a WeakMap");
15
+
16
+ export const serviceIdentities: WeakMap<ServiceDefinition, ServiceIdentity> =
17
+ existing instanceof WeakMap ? existing : new WeakMap();
18
+
19
+ if (existing === undefined)
20
+ Object.defineProperty(globalThis, identityKey, { value: serviceIdentities });
@@ -0,0 +1,46 @@
1
+ import { refuse } from "../error.ts";
2
+ import { Errors } from "../errors.ts";
3
+ import { serviceIdentities, type ServiceIdentity } from "./service-identities.ts";
4
+ import type { AcquisitionOptions, ServiceDefinition } from "./types.ts";
5
+
6
+ /** Associate original and captured services only after the whole orb declaration succeeds. */
7
+ export function associateServices(
8
+ orb: string,
9
+ apiVersion: number,
10
+ services: readonly (readonly [string, ServiceDefinition, ServiceDefinition])[],
11
+ ): void {
12
+ const pending = new Map<ServiceDefinition, ServiceIdentity>();
13
+ for (const [name, original, captured] of services) {
14
+ const identity = { orb, name, apiVersion };
15
+ for (const definition of [original, captured]) {
16
+ const previous = pending.get(definition) ?? serviceIdentities.get(definition);
17
+ if (
18
+ previous &&
19
+ (previous.orb !== orb || previous.name !== name || previous.apiVersion !== apiVersion)
20
+ )
21
+ refuse(
22
+ Errors.Invalid.Service,
23
+ "A service definition must have one orb, name and API version",
24
+ );
25
+ pending.set(definition, identity);
26
+ }
27
+ }
28
+ for (const [definition, identity] of pending) serviceIdentities.set(definition, identity);
29
+ }
30
+
31
+ /** Resolve a declared service without changing the kernel's named acquisition or authority rules. */
32
+ export function serviceAcquisition(
33
+ service: string | ServiceDefinition,
34
+ options: AcquisitionOptions = {},
35
+ ): { name: string; options: AcquisitionOptions } {
36
+ if (typeof service === "string") return { name: service, options };
37
+ const identity = serviceIdentities.get(service);
38
+ if (!identity)
39
+ refuse(Errors.Invalid.Service, "Declare this service in an orb before acquiring it");
40
+ if (options.apiVersion !== undefined && options.apiVersion !== identity.apiVersion)
41
+ refuse(
42
+ Errors.Invalid.Service,
43
+ "The acquisition API version must match the service declaration",
44
+ );
45
+ return { name: identity.name, options: { ...options, apiVersion: identity.apiVersion } };
46
+ }