@makaio/framework 1.0.0-dev-1784889676396 → 1.0.0-dev-1785347612784

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