@makaio/framework 1.0.0-dev-1786014320559 → 1.0.0-dev-1787670071418

package/dist/index-Bqk0pJBQ2.d.mts

@@ -0,0 +1,138 @@
+import { f as ResolveLiveIdentityResponse, o as ResolveIdRequest, u as ResolveLiveIdentityRequest } from "./schemas-C1mxTfd7.mjs";
+import { IMakaioBus } from "@makaio/framework/bus";
+
+//#region services/core/src/adapter-runtime/identity.d.ts
+/**
+ * Build the deterministic runtime adapter id for a machine-local adapter.
+ * @param machineId - Runtime machine identifier.
+ * @param adapterName - Stable adapter driver name.
+ * @returns Deterministic UUID-shaped runtime adapter id.
+ */
+declare function buildDeterministicAdapterId(machineId: string, adapterName: string): string;
+/**
+ * Derive an adapter id request against the requested machine.
+ *
+ * This deliberately does not inspect local runtime state. Local callers that
+ * need a dispatchable adapter must use the live-instance resolver installed by
+ * {@link registerAdapterRuntimeIdentityHandlers}; explicitly foreign requests
+ * remain deterministic until a targeted remote lookup is available.
+ * @param request - Forward lookup payload.
+ * @param currentMachineId - Runtime-default machine identifier.
+ * @returns Deterministic UUID-shaped runtime adapter id.
+ */
+declare function resolveDeterministicAdapterId(request: ResolveIdRequest, currentMachineId?: string): string;
+/**
+ * Service-lifetime adapter identity index.
+ */
+declare class AdapterIdentityRegistry {
+  private readonly currentMachineId?;
+  private readonly adapterNamesById;
+  private readonly liveIdentities;
+  private localAdapterIds;
+  /**
+   * Create a new identity registry.
+   * @param currentMachineId - Runtime-default machine identifier.
+   */
+  constructor(currentMachineId?: string | undefined);
+  /**
+   * Replace the set of locally known adapters while preserving remote ids
+   * already resolved during this service lifetime.
+   * @param adapterNames - Current local adapter names.
+   */
+  replaceKnownAdapterNames(adapterNames: Iterable<string>): void;
+  /**
+   * Resolve and remember an adapter id.
+   * @param request - Forward lookup payload.
+   * @returns Deterministic runtime adapter id.
+   */
+  resolveId(request: ResolveIdRequest): string;
+  /**
+   * Remember a resolved adapter id without re-deriving it.
+   * @param adapterId - Runtime adapter id.
+   * @param adapterName - Stable adapter driver name.
+   */
+  rememberAdapterId(adapterId: string, adapterName: string): void;
+  /**
+   * Remember an adapter identity announced by a live runtime instance.
+   *
+   * This is intentionally separate from {@link rememberAdapterId}: reverse
+   * lookup may learn deterministic or catalog identities, but only an
+   * initialization announcement proves that an opaque instance ID is currently
+   * hosted by one particular machine.
+   * @param identity - Exact identity reported by `adapter.initialized`.
+   */
+  rememberLiveIdentity(identity: ResolveLiveIdentityResponse): void;
+  /**
+   * Resolve one live identity only when every supplied half matches its
+   * initialization announcement.
+   * @param identity - Exact identity a caller intends to dispatch to.
+   * @returns The announced identity, or `undefined` when it is unknown or differs.
+   */
+  resolveLiveIdentity(identity: ResolveLiveIdentityRequest): ResolveLiveIdentityResponse | undefined;
+  /**
+   * Forget a withdrawn instance without disturbing a newer reuse of its ID.
+   * @param identity - Exact identity withdrawn by the adapter lifecycle.
+   */
+  forgetLiveIdentity(identity: ResolveLiveIdentityResponse): void;
+  /**
+   * Resolve a runtime adapter id back to its known adapter name.
+   * @param adapterId - Runtime adapter id.
+   * @returns Adapter name when known.
+   */
+  resolveAdapterName(adapterId: string): string | undefined;
+  /**
+   * Hydrate local deterministic adapter names from the provided catalog and
+   * retry the reverse lookup.
+   * @param adapterId - Runtime adapter id to resolve.
+   * @param listKnownAdapterNames - Canonical name supplier.
+   * @returns Adapter name when known after hydration.
+   */
+  resolveAdapterNameFromKnownNames(adapterId: string, listKnownAdapterNames: () => Promise<Iterable<string>>): Promise<string | undefined>;
+  /**
+   * Clear all remembered ids.
+   */
+  clear(): void;
+}
+/**
+ * Registered adapter identity helpers for tests and lightweight hosts.
+ */
+interface RegisteredAdapterRuntimeIdentityHandlers {
+  /** Mutable identity registry backing the registered handlers. */
+  readonly registry: AdapterIdentityRegistry;
+  /** Cleanup function that unregisters the handlers. */
+  readonly cleanup: () => void;
+}
+/**
+ * Resolve a locally live adapter name to the instance id it is registered under.
+ *
+ * Returning `undefined` means no dispatchable local instance currently owns the
+ * name. The port is synchronous because its authoritative source is the
+ * runtime's in-memory instance registry.
+ */
+type ResolveLiveAdapterId = (adapterName: string) => string | undefined;
+/** Resolve one exact current identity from the runtime-owned live registry. */
+type ResolveLiveAdapterIdentity = (adapterId: string) => ResolveLiveIdentityResponse | undefined;
+/** Runtime identity configuration. */
+interface AdapterRuntimeIdentityHandlerOptions {
+  /** Runtime-default machine identifier. */
+  readonly currentMachineId?: string;
+  /** Local live-instance resolver supplied by the host runtime. */
+  readonly resolveLiveAdapterId?: ResolveLiveAdapterId;
+  /** Current live identity resolver; makes proofs replayable after boot and retractions immediate. */
+  readonly resolveLiveAdapterIdentity?: ResolveLiveAdapterIdentity;
+  /** Snapshot used to seed handlers registered after adapter startup. */
+  readonly listLiveAdapterIdentities?: () => Iterable<ResolveLiveIdentityResponse>;
+  /** Static local names for lightweight host compatibility. */
+  readonly knownAdapterNames?: Iterable<string>;
+  /** Lazy local-name enumeration for reverse lookup compatibility. */
+  readonly listKnownAdapterNames?: () => Promise<Iterable<string>>;
+}
+/**
+ * Register runtime adapter identity handlers.
+ * @param bus - Bus instance used for registration.
+ * @param options - Runtime identity configuration.
+ * @returns Registry instance and cleanup function.
+ */
+declare function registerAdapterRuntimeIdentityHandlers(bus: IMakaioBus, options?: AdapterRuntimeIdentityHandlerOptions): RegisteredAdapterRuntimeIdentityHandlers;
+//#endregion
+export { ResolveLiveAdapterIdentity as a, resolveDeterministicAdapterId as c, ResolveLiveAdapterId as i, AdapterRuntimeIdentityHandlerOptions as n, buildDeterministicAdapterId as o, RegisteredAdapterRuntimeIdentityHandlers as r, registerAdapterRuntimeIdentityHandlers as s, AdapterIdentityRegistry as t };

package/dist/{index-CB4aIUoF.d.mts → index-BuMsrli0.d.mts}

@@ -11,8 +11,8 @@ import * as _$_makaio_core0 from "@makaio/framework/core";
  */
 declare const FacetAuthoritySchema: z.ZodEnum<{
   system: "system";
-  human: "human";
   agent: "agent";
+  human: "human";
 }>;
 /**
  * Cardinality of values a facet namespace permits per target.
@@ -32,8 +32,8 @@ declare const FacetCardinalitySchema: z.ZodEnum<{
  * - `'surface'` — a UI surface or layout area
  */
 declare const FacetAppliesToSchema: z.ZodEnum<{
-  workpiece: "workpiece";
   artifact: "artifact";
+  workpiece: "workpiece";
   surface: "surface";
 }>;
 /**
@@ -53,12 +53,12 @@ declare const FacetNamespaceRegistrationSchema: z.ZodObject<{
   values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
   authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
     system: "system";
-    human: "human";
     agent: "agent";
+    human: "human";
   }>>>;
   appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-    workpiece: "workpiece";
     artifact: "artifact";
+    workpiece: "workpiece";
     surface: "surface";
   }>>>;
   description: z.ZodOptional<z.ZodString>;
@@ -157,12 +157,12 @@ declare const FacetSchemas: {
       values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
       authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
         system: "system";
-        human: "human";
         agent: "agent";
+        human: "human";
       }>>>;
       appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-        workpiece: "workpiece";
         artifact: "artifact";
+        workpiece: "workpiece";
         surface: "surface";
       }>>>;
       description: z.ZodOptional<z.ZodString>;
@@ -185,12 +185,12 @@ declare const FacetSchemas: {
         values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
         authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
           system: "system";
-          human: "human";
           agent: "agent";
+          human: "human";
         }>>>;
         appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-          workpiece: "workpiece";
           artifact: "artifact";
+          workpiece: "workpiece";
           surface: "surface";
         }>>>;
         description: z.ZodOptional<z.ZodString>;
@@ -223,12 +223,12 @@ declare const FacetNamespace: _$_makaio_core0.BusNamespaceDefinition<"facet", {
       values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
       authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
         system: "system";
-        human: "human";
         agent: "agent";
+        human: "human";
       }>>>;
       appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-        workpiece: "workpiece";
         artifact: "artifact";
+        workpiece: "workpiece";
         surface: "surface";
       }>>>;
       description: z.ZodOptional<z.ZodString>;
@@ -251,12 +251,12 @@ declare const FacetNamespace: _$_makaio_core0.BusNamespaceDefinition<"facet", {
         values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
         authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
           system: "system";
-          human: "human";
           agent: "agent";
+          human: "human";
         }>>>;
         appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-          workpiece: "workpiece";
           artifact: "artifact";
+          workpiece: "workpiece";
           surface: "surface";
         }>>>;
         description: z.ZodOptional<z.ZodString>;
@@ -295,12 +295,12 @@ declare const FacetSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSub
       values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
       authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
         system: "system";
-        human: "human";
         agent: "agent";
+        human: "human";
       }>>>;
       appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-        workpiece: "workpiece";
         artifact: "artifact";
+        workpiece: "workpiece";
         surface: "surface";
       }>>>;
       description: z.ZodOptional<z.ZodString>;
@@ -323,12 +323,12 @@ declare const FacetSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSub
         values: z.ZodUnion<readonly [z.ZodLiteral<"open">, z.ZodReadonly<z.ZodArray<z.ZodString>>]>;
         authority: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
           system: "system";
-          human: "human";
           agent: "agent";
+          human: "human";
         }>>>;
         appliesTo: z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-          workpiece: "workpiece";
           artifact: "artifact";
+          workpiece: "workpiece";
           surface: "surface";
         }>>>;
         description: z.ZodOptional<z.ZodString>;