@makaio/framework 1.0.0-dev-1784806252593 → 1.0.0-dev-1785344643235

package/dist/index-B0Kf_OWi.d.mts

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { TransitionActionFactory, TransitionActionInvocation, TransitionEvaluationContext, TransitionEventType, TransitionRuleDefinition, TransitionRuleDefinitionSchema } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { Condition } from "@makaio/framework/rules";
+import { ContributionProcessor } from "@makaio/framework/kernel";
+
+//#region services/core/src/workflow-transitions/transition-action-registry.d.ts
+/**
+ * Built-in action type identifier for starting a workflow via the bus.
+ *
+ * Input fields (all optional):
+ * - `workflowId` — required workflow ID
+ * - `input` — workflow input payload
+ * - `inputExpression` — jexl expression resolving workflow input from the transition context
+ * - `config` — workflow config overrides
+ * - `artifactRef` — explicit artifact binding target
+ * - `scope` — execution scope override
+ */
+declare const WORKFLOW_START_ACTION_TYPE = "workflow.start";
+/**
+ * Registry for executable transition action factories.
+ *
+ * Manages built-in actions (seeded at construction) and extension-contributed
+ * actions. Duplicate action type keys hard-fail registration. Source keys
+ * support clean deregistration on extension stop.
+ *
+ * Unlike rules, actions are executable (factory-based), not static. Each
+ * dispatch call creates a fresh handler via the registered factory.
+ */
+declare class TransitionActionRegistry {
+  /** All factories indexed by action type string. */
+  private readonly factories;
+  /** Factories indexed by source key for deregistration. */
+  private readonly factoriesBySource;
+  /**
+   * @param bus - Bus instance forwarded to the built-in `workflow.start` factory.
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Register custom action factories from a source (extension name).
+   *
+   * Source keys and type keys are checked for collisions before any mutations.
+   * Built-in action types (`workflow.start`) may not be overridden.
+   * @param sourceKey - Stable source identifier (extension name).
+   * @param actions - Map of action type string to factory.
+   * @throws If the source or any action type collides with an existing registration.
+   */
+  register(sourceKey: string, actions: Readonly<Record<string, TransitionActionFactory>>): void;
+  /**
+   * Deregister all action factories contributed by a source.
+   *
+   * Built-in actions (`__builtin__`) cannot be deregistered.
+   * No-op when the source has no registered factories.
+   * @param sourceKey - Source identifier previously passed to {@link register}.
+   */
+  deregister(sourceKey: string): void;
+  /**
+   * Resolve and invoke the action handler for the given invocation.
+   *
+   * Creates a fresh handler via the registered factory, then delegates
+   * execution to the handler's `execute` method.
+   * @param invocation - Action invocation descriptor from the matched rule.
+   * @param context - Evaluation context from the triggering artifact event.
+   * @throws If no factory is registered for `invocation.type`.
+   */
+  dispatch(invocation: TransitionActionInvocation, context: TransitionEvaluationContext): Promise<void>;
+  /**
+   * Check whether an action type is registered.
+   * @param actionType - Action type identifier to check.
+   * @returns `true` when the type has a registered factory.
+   */
+  has(actionType: string): boolean;
+  /**
+   * List all registered action type strings.
+   * @returns Array of registered action type identifiers.
+   */
+  listTypes(): string[];
+}
+//#endregion
+//#region services/core/src/workflow-transitions/transition-rule-registry.d.ts
+type TransitionRuleDefinitionInput = z.input<typeof TransitionRuleDefinitionSchema>;
+interface SourceSnapshot {
+  ruleIds: readonly string[];
+}
+/**
+ * A {@link TransitionRuleDefinition} with its optional `when` condition
+ * pre-parsed at registration time so the pipeline avoids re-parsing on
+ * every incoming artifact event.
+ */
+interface PreparedTransitionRule {
+  /** The original serializable rule definition. */
+  readonly rule: TransitionRuleDefinition;
+  /**
+   * Pre-parsed condition produced by `ConditionSchema.parse(rule.when)`.
+   * `undefined` when the rule has no `when` clause — it always matches.
+   */
+  readonly condition: Condition | undefined;
+}
+/**
+ * Registry for serializable transition rules contributed by workflow bundles
+ * and extensions.
+ *
+ * Rules are stored under a stable source key (bundle ID or extension name) and
+ * indexed by event type for fast pipeline evaluation. Duplicate rule IDs
+ * hard-fail registration across all sources. Source keys support clean
+ * deregistration.
+ *
+ * Rules are purely static and serializable — no functions.
+ */
+declare class TransitionRuleRegistry {
+  /** All rules indexed by source key. */
+  private readonly rulesBySource;
+  /** Index: event type → flat list of prepared rules across all sources. */
+  private readonly rulesByEventType;
+  /** All registered rule IDs for collision detection. */
+  private readonly ruleIdSet;
+  /**
+   * Register transition rules from a source (bundle or extension).
+   *
+   * The source key, rule definitions, rule IDs, and conditions are checked
+   * before any mutations are applied — registration is atomic: either all rules
+   * from the source are added or none are.
+   * @param sourceKey - Stable identifier for the contributing source (bundle ID or extension name).
+   * @param rules - Rule definitions to register. IDs must not collide with existing registrations.
+   * @throws If the source or any rule ID collides, or if any rule definition or condition is invalid.
+   */
+  register(sourceKey: string, rules: readonly TransitionRuleDefinitionInput[]): void;
+  /**
+   * Deregister all rules contributed by a source.
+   *
+   * No-op when the source has no registered rules.
+   * @param sourceKey - Source identifier previously passed to {@link register}.
+   */
+  deregister(sourceKey: string): void;
+  /**
+   * Return all enabled prepared rules matching the given event type.
+   *
+   * Returns a shallow copy of the internal bucket to prevent external mutation.
+   * Each entry carries the original rule definition alongside its pre-parsed
+   * condition so the pipeline avoids re-parsing per event.
+   * @param eventType - Artifact event type to query.
+   * @returns Enabled prepared rules registered for the event type.
+   */
+  getRulesForEvent(eventType: TransitionEventType): PreparedTransitionRule[];
+  /**
+   * Snapshot the current rule IDs registered under a source.
+   *
+   * Used for diagnostics and deduplication checks.
+   * @param sourceKey - Source identifier.
+   * @returns Snapshot of registered rule IDs, or `undefined` if the source has no rules.
+   */
+  snapshotSource(sourceKey: string): SourceSnapshot | undefined;
+}
+//#endregion
+//#region services/core/src/workflow-transitions/transition-pipeline-service.d.ts
+/**
+ * Service that watches artifact bus events and fires transition rules.
+ *
+ * On initialization the service subscribes to the three artifact lifecycle
+ * events (`artifact.created`, `artifact.revised`, `artifact.status.changed`).
+ * For each incoming event it evaluates the registered rules for that event type
+ * using `@makaio/rules`, then dispatches the matching rule's action through the
+ * {@link TransitionActionRegistry}.
+ *
+ * Loop protection: the service maintains an in-memory depth counter keyed by
+ * `${kind}:${id}` for each artifact. Each time a `workflow.start` action is
+ * dispatched for an artifact the counter is incremented. Incoming events for an
+ * artifact whose counter has reached {@link MAX_TRANSITION_DEPTH} are silently
+ * dropped. Counters are pruned after {@link DEPTH_ENTRY_TTL_MS} to prevent
+ * unbounded growth.
+ */
+declare class TransitionPipelineService extends BaseService {
+  /** Registry of serializable transition rules. */
+  readonly ruleRegistry: TransitionRuleRegistry;
+  /** Registry of executable action factories. */
+  readonly actionRegistry: TransitionActionRegistry;
+  /**
+   * In-memory depth tracker keyed by `${kind}:${id}`.
+   *
+   * Counts how many `workflow.start` actions have been dispatched for each
+   * artifact in the current execution chain. Entries expire after
+   * {@link DEPTH_ENTRY_TTL_MS}.
+   */
+  private readonly depthMap;
+  /**
+   * @param bus - Bus instance used for artifact event subscriptions and workflow.start dispatch.
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Subscribe to all three artifact lifecycle event types.
+   */
+  protected onInit(): void;
+  /**
+   * Evaluate all enabled rules for the event type, then dispatch matching actions.
+   * @param eventType - The artifact event type that fired.
+   * @param contextBase - Partial evaluation context built from the event payload.
+   */
+  private handleArtifactEvent;
+  /**
+   * Resolve a status-change artifact ref into the exact revision that emitted
+   * the event before rule evaluation.
+   * @param ref - Revisioned artifact reference from the status.changed event.
+   * @returns Full artifact revision, or `undefined` when the artifact store cannot provide it.
+   */
+  private resolveStatusChangedArtifact;
+  /**
+   * Resolve the previous revision for an artifact.revised event.
+   *
+   * The original `previous` context value remains the event's artifact ref for
+   * compatibility; this helper adds a full `previousArtifact` snapshot when the
+   * artifact store can provide it so rules can compare before/after state.
+   * @param ref - Revisioned artifact reference from the revised event.
+   * @returns Full previous artifact revision, or `undefined` when unavailable.
+   */
+  private resolvePreviousRevisedArtifact;
+  /**
+   * Evaluate a single prepared rule condition and dispatch its action if the condition matches.
+   *
+   * The condition is pre-parsed at registration time, so this method only evaluates it
+   * against the current event context — no schema parsing overhead per event.
+   *
+   * When dispatch succeeds and the action type is `workflow.start`, the in-memory
+   * depth counter for the artifact is incremented so subsequent events in the same
+   * execution chain are correctly depth-checked.
+   * @param entry - The prepared rule (definition + pre-parsed condition) to evaluate.
+   * @param eventType - The artifact event type.
+   * @param contextBase - Partial evaluation context from the event payload.
+   * @param artifactKey - Composite `${kind}:${id}` key for depth tracking.
+   * @param incomingDepth - Current loop-protection depth for this artifact.
+   */
+  private evaluateAndDispatch;
+  /**
+   * Derive the composite artifact key used for depth tracking.
+   * @param artifact - Artifact ref or revision from the event payload.
+   * @returns A `${kind}:${id}` string, falling back to `'unknown:unknown'` when
+   * the artifact lacks these fields.
+   */
+  private artifactKey;
+  /**
+   * Read the current dispatch depth for the given artifact key.
+   *
+   * Prunes stale entries lazily on each read so the map does not grow
+   * unboundedly when artifacts are no longer active.
+   * @param key - Composite `${kind}:${id}` key.
+   * @returns Current dispatch count, or `0` when absent or expired.
+   */
+  private readDepth;
+  /**
+   * Increment the dispatch depth counter for the given artifact key and reset its TTL.
+   * @param key - Composite `${kind}:${id}` key.
+   */
+  private incrementDepth;
+}
+//#endregion
+//#region services/core/src/workflow-transitions/transition-contribution-processor.d.ts
+/**
+ * Processes transition rule and action contributions from extensions.
+ *
+ * During activation: validates namespace prefixes, then registers rules and
+ * actions with the {@link TransitionPipelineService}. On stop: deregisters
+ * all contributions from that extension.
+ * @returns Contribution processor for transition pipeline registration.
+ */
+declare function createTransitionContributionProcessor(): ContributionProcessor;
+//#endregion
+export { WORKFLOW_START_ACTION_TYPE as a, TransitionActionRegistry as i, TransitionPipelineService as n, TransitionRuleRegistry as r, createTransitionContributionProcessor as t };

package/dist/{index-DRiTICBU.d.mts → index-BAXkicoQ.d.mts}

@@ -1,4 +1,4 @@
-import { t as AdapterAuthBinding } from "./adapter-binding-Dfk_g-lP.mjs";
+import { t as AdapterAuthBinding } from "./adapter-binding-DQchUtrK.mjs";
 import { z } from "zod";
 
 //#region core/contracts/src/auth/definitions.d.ts

package/dist/{index-D9Tk7hyM.d.mts → index-BC79QrGC.d.mts}

@@ -1,4 +1,4 @@
-import { H as ClientDefinition, U as ClientDefinitionInput } from "./hook-responses-Dg8wDvRo.mjs";
+import { H as ClientDefinition, U as ClientDefinitionInput } from "./hook-responses-Dh1PWXqJ.mjs";
 import * as _$zod from "zod";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";
@@ -17,8 +17,8 @@ declare const ClientExecutionContextSchema: z.ZodObject<{
   env: z.ZodRecord<z.ZodString, z.ZodString>;
   configDir: z.ZodNullable<z.ZodString>;
   source: z.ZodEnum<{
-    managed: "managed";
     global: "global";
+    managed: "managed";
   }>;
   version: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
@@ -39,8 +39,8 @@ declare const ClientResolveBinarySchema: {
     sessionId: z.ZodOptional<z.ZodString>;
     projectDir: z.ZodOptional<z.ZodString>;
     preferSource: z.ZodOptional<z.ZodEnum<{
-      managed: "managed";
       global: "global";
+      managed: "managed";
     }>>;
     harnessId: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
@@ -49,8 +49,8 @@ declare const ClientResolveBinarySchema: {
     env: z.ZodRecord<z.ZodString, z.ZodString>;
     configDir: z.ZodNullable<z.ZodString>;
     source: z.ZodEnum<{
-      managed: "managed";
       global: "global";
+      managed: "managed";
     }>;
     version: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>;
@@ -89,9 +89,9 @@ declare const ClientSchemas: {
       baseConfigDir: z.ZodOptional<z.ZodString>;
       projectDir: z.ZodOptional<z.ZodString>;
       configInheritance: z.ZodOptional<z.ZodEnum<{
+        empty: "empty";
         "auth-only": "auth-only";
         full: "full";
-        empty: "empty";
       }>>;
     }, z.core.$strip>;
     response: z.ZodObject<{
@@ -258,8 +258,8 @@ declare const ClientSchemas: {
     clientRuntimeId: z.ZodString;
     clientId: z.ZodString;
     status: z.ZodEnum<{
-      observed: "observed";
       started: "started";
+      observed: "observed";
     }>;
     source: z.ZodObject<{
       layer: z.ZodEnum<{
@@ -648,8 +648,8 @@ declare const ClientSchemas: {
       "signed-binary-bucket": "signed-binary-bucket";
     }>;
     stage: z.ZodEnum<{
-      resolving: "resolving";
       downloading: "downloading";
+      resolving: "resolving";
       verifying: "verifying";
       extracting: "extracting";
       installing: "installing";
@@ -688,8 +688,8 @@ declare const ClientSchemas: {
     reason: z.ZodEnum<{
       update: "update";
       install: "install";
-      uninstall: "uninstall";
       "set-active": "set-active";
+      uninstall: "uninstall";
     }>;
   }, z.core.$strip>;
   resolveBinary: {
@@ -698,8 +698,8 @@ declare const ClientSchemas: {
       sessionId: z.ZodOptional<z.ZodString>;
       projectDir: z.ZodOptional<z.ZodString>;
       preferSource: z.ZodOptional<z.ZodEnum<{
-        managed: "managed";
         global: "global";
+        managed: "managed";
       }>>;
       harnessId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -708,8 +708,8 @@ declare const ClientSchemas: {
       env: z.ZodRecord<z.ZodString, z.ZodString>;
       configDir: z.ZodNullable<z.ZodString>;
       source: z.ZodEnum<{
-        managed: "managed";
         global: "global";
+        managed: "managed";
       }>;
       version: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
@@ -1159,8 +1159,8 @@ type ClientSetActiveResponse = z.infer<typeof ClientSetActiveSchema.response>;
  * - `'activating'`   — marking the installed version as active.
  */
 declare const InstallStageSchema: z.ZodEnum<{
-  resolving: "resolving";
   downloading: "downloading";
+  resolving: "resolving";
   verifying: "verifying";
   extracting: "extracting";
   installing: "installing";
@@ -1183,8 +1183,8 @@ declare const ClientInstallProgressSchema: z.ZodObject<{
     "signed-binary-bucket": "signed-binary-bucket";
   }>;
   stage: z.ZodEnum<{
-    resolving: "resolving";
     downloading: "downloading";
+    resolving: "resolving";
     verifying: "verifying";
     extracting: "extracting";
     installing: "installing";
@@ -1246,8 +1246,8 @@ declare const ClientVersionChangedSchema: z.ZodObject<{
   reason: z.ZodEnum<{
     update: "update";
     install: "install";
-    uninstall: "uninstall";
     "set-active": "set-active";
+    uninstall: "uninstall";
   }>;
 }, z.core.$strip>;
 type ClientVersionChanged = z.infer<typeof ClientVersionChangedSchema>;
@@ -1382,8 +1382,8 @@ declare const ClientRuntimeStartedSchema: z.ZodObject<{
   clientRuntimeId: z.ZodString;
   clientId: z.ZodString;
   status: z.ZodEnum<{
-    observed: "observed";
     started: "started";
+    observed: "observed";
   }>;
   source: z.ZodObject<{
     layer: z.ZodEnum<{
@@ -1675,9 +1675,9 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
       baseConfigDir: _$zod.ZodOptional<_$zod.ZodString>;
       projectDir: _$zod.ZodOptional<_$zod.ZodString>;
       configInheritance: _$zod.ZodOptional<_$zod.ZodEnum<{
+        empty: "empty";
         "auth-only": "auth-only";
         full: "full";
-        empty: "empty";
       }>>;
     }, _$zod_v4_core0.$strip>;
     response: _$zod.ZodObject<{
@@ -1844,8 +1844,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
     clientRuntimeId: _$zod.ZodString;
     clientId: _$zod.ZodString;
     status: _$zod.ZodEnum<{
-      observed: "observed";
       started: "started";
+      observed: "observed";
     }>;
     source: _$zod.ZodObject<{
       layer: _$zod.ZodEnum<{
@@ -2218,8 +2218,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
       "signed-binary-bucket": "signed-binary-bucket";
     }>;
     stage: _$zod.ZodEnum<{
-      resolving: "resolving";
       downloading: "downloading";
+      resolving: "resolving";
       verifying: "verifying";
       extracting: "extracting";
       installing: "installing";
@@ -2258,8 +2258,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
     reason: _$zod.ZodEnum<{
       update: "update";
       install: "install";
-      uninstall: "uninstall";
       "set-active": "set-active";
+      uninstall: "uninstall";
     }>;
   }, _$zod_v4_core0.$strip>;
   resolveBinary: {
@@ -2268,8 +2268,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
       sessionId: _$zod.ZodOptional<_$zod.ZodString>;
       projectDir: _$zod.ZodOptional<_$zod.ZodString>;
       preferSource: _$zod.ZodOptional<_$zod.ZodEnum<{
-        managed: "managed";
         global: "global";
+        managed: "managed";
       }>>;
       harnessId: _$zod.ZodOptional<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2278,8 +2278,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
       env: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodString>;
       configDir: _$zod.ZodNullable<_$zod.ZodString>;
       source: _$zod.ZodEnum<{
-        managed: "managed";
         global: "global";
+        managed: "managed";
       }>;
       version: _$zod.ZodNullable<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2315,9 +2315,9 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
       baseConfigDir: _$zod.ZodOptional<_$zod.ZodString>;
       projectDir: _$zod.ZodOptional<_$zod.ZodString>;
       configInheritance: _$zod.ZodOptional<_$zod.ZodEnum<{
+        empty: "empty";
         "auth-only": "auth-only";
         full: "full";
-        empty: "empty";
       }>>;
     }, _$zod_v4_core0.$strip>;
     response: _$zod.ZodObject<{
@@ -2484,8 +2484,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
     clientRuntimeId: _$zod.ZodString;
     clientId: _$zod.ZodString;
     status: _$zod.ZodEnum<{
-      observed: "observed";
       started: "started";
+      observed: "observed";
     }>;
     source: _$zod.ZodObject<{
       layer: _$zod.ZodEnum<{
@@ -2858,8 +2858,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
       "signed-binary-bucket": "signed-binary-bucket";
     }>;
     stage: _$zod.ZodEnum<{
-      resolving: "resolving";
       downloading: "downloading";
+      resolving: "resolving";
       verifying: "verifying";
       extracting: "extracting";
       installing: "installing";
@@ -2898,8 +2898,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
     reason: _$zod.ZodEnum<{
       update: "update";
       install: "install";
-      uninstall: "uninstall";
       "set-active": "set-active";
+      uninstall: "uninstall";
     }>;
   }, _$zod_v4_core0.$strip>;
   resolveBinary: {
@@ -2908,8 +2908,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
       sessionId: _$zod.ZodOptional<_$zod.ZodString>;
       projectDir: _$zod.ZodOptional<_$zod.ZodString>;
       preferSource: _$zod.ZodOptional<_$zod.ZodEnum<{
-        managed: "managed";
         global: "global";
+        managed: "managed";
       }>>;
       harnessId: _$zod.ZodOptional<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2918,8 +2918,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
       env: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodString>;
       configDir: _$zod.ZodNullable<_$zod.ZodString>;
       source: _$zod.ZodEnum<{
-        managed: "managed";
         global: "global";
+        managed: "managed";
       }>;
       version: _$zod.ZodNullable<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2978,9 +2978,9 @@ declare const SessionConfigEnvSchema: z.ZodRecord<z.ZodString, z.ZodString>;
  * Policy for materializing a session config directory from a base client config.
  */
 declare const SessionConfigInheritanceSchema: z.ZodEnum<{
+  empty: "empty";
   "auth-only": "auth-only";
   full: "full";
-  empty: "empty";
 }>;
 type SessionConfigInheritance = z.infer<typeof SessionConfigInheritanceSchema>;
 /**
@@ -3136,9 +3136,9 @@ declare const ClientSessionConfigSchemas: {
       baseConfigDir: z.ZodOptional<z.ZodString>;
       projectDir: z.ZodOptional<z.ZodString>;
       configInheritance: z.ZodOptional<z.ZodEnum<{
+        empty: "empty";
         "auth-only": "auth-only";
         full: "full";
-        empty: "empty";
       }>>;
     }, z.core.$strip>;
     response: z.ZodObject<{
@@ -3192,9 +3192,9 @@ declare const SessionConfigSetupRequestSchema: z.ZodObject<{
     win32: "win32";
   }>;
   configInheritance: z.ZodEnum<{
+    empty: "empty";
     "auth-only": "auth-only";
     full: "full";
-    empty: "empty";
   }>;
 }, z.core.$strip>;
 type SessionConfigSetupRequest = z.infer<typeof SessionConfigSetupRequestSchema>;