@memberjunction/task-graph 0.0.0 → 6.1.0-edge.2

package/dist/WorkflowSpecSync.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview Persists a `WorkflowSpec` by **reconciling substrates that already exist**.
+ *
+ * **The central design constraint: no new storage.** There is no `Workflow` table and there will not
+ * be one. A workflow's WHAT is a Flow agent (the graph); its WHEN is a Scheduled Job or an Entity
+ * Action binding. Inventing a parallel `Workflow` row would create a second definition of "a
+ * scheduled thing", and the scheduler would then have two masters that can disagree — which is
+ * exactly the class of divergence this whole program has been removing.
+ *
+ * So this is a **reconciler**, not a writer. It follows the pattern
+ * `MJRecordProcessEntityServer.Save()` already proved: resolve the job type, find the rows this
+ * definition owns, then upsert or disable them so the substrate matches the spec. Rows are matched
+ * by a marker in their own `Configuration`, which is what makes ownership survive a rename.
+ *
+ * **Agent persistence crosses a seam.** Writing the Flow agent behind the graph is `AgentSpecSync`'s
+ * job — it already owns atomic multi-entity agent writes and the mutation audit. Importing it here
+ * would pull the agent-manager package into the execution substrate, so the host injects it instead.
+ * A caller with no agent writer still gets correct trigger reconciliation and an honest error rather
+ * than a half-persisted workflow.
+ *
+ * @module @memberjunction/task-graph
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { type WorkflowSpec } from '@memberjunction/ai-core-plus';
+/**
+ * Scheduled Job Type that runs a workflow's Flow agent.
+ *
+ * `'Agent'` is an existing seeded type backed by `AgentScheduledJobDriver` — a workflow's schedule
+ * reuses it rather than introducing a parallel one. `ScheduledJobType.DriverClass` is UNIQUE, so a
+ * second type for the same driver is not merely redundant, it is impossible; discovering that is
+ * what confirmed the substrate was already there and only the authoring surface was missing.
+ */
+export declare const RUN_WORKFLOW_JOB_TYPE = "Agent";
+/** Marker written into an owned row's `Configuration`, so ownership survives a rename. */
+export declare const WORKFLOW_OWNER_KEY = "WorkflowAgentID";
+/**
+ * The Action an entity-change trigger dispatches to.
+ *
+ * `Execute Agent` already exists and was written for exactly this: "a concrete dispatch target for
+ * `AIAgent.ExposeAsAction`". Entity-action *invocation* is likewise already wired — the save pipeline
+ * fires validate / before-save / after-save / before-delete / after-delete through
+ * `HandleEntityActions`. So an entity-change trigger needs no new machinery at all; it needs a
+ * binding row, which is what this creates.
+ */
+export declare const EXECUTE_AGENT_ACTION = "Execute Agent";
+/** Everything reconciliation needs beyond the spec itself. */
+export type WorkflowSyncContext = {
+    ContextUser: UserInfo;
+    Provider: IMetadataProvider;
+};
+/**
+ * Persists the Flow agent behind a workflow's graph.
+ *
+ * Injected rather than imported so this package does not depend on the agent-manager. The host
+ * supplies an implementation backed by `AgentSpecSync`, which is the one place that writes an agent.
+ */
+export type WorkflowAgentWriter = {
+    /** Creates or updates the Flow agent for this workflow. Returns its ID. */
+    PersistFlowAgent(spec: WorkflowSpec, context: WorkflowSyncContext): Promise<string>;
+};
+export type WorkflowSyncResult = {
+    Success: boolean;
+    /** The Flow agent the workflow's graph persisted as — the handle for everything downstream. */
+    AgentID?: string;
+    /** Scheduled Jobs created, updated or disabled by this reconciliation. */
+    ScheduledJobIDs: string[];
+    /** Triggers the spec asked for that this build cannot yet reconcile, stated rather than dropped. */
+    Unreconciled: string[];
+    ErrorMessage?: string;
+};
+export declare class WorkflowSpecSync {
+    private readonly agentWriter;
+    constructor(agentWriter?: WorkflowAgentWriter | null);
+    /**
+     * Reconciles every substrate a workflow owns, so they match the spec.
+     *
+     * Order matters: the agent is persisted first because a Scheduled Job needs its ID to point at,
+     * and a job pointing at an agent that does not exist would be a scheduled no-op — the failure
+     * mode where everything looks configured and nothing ever runs.
+     */
+    Persist(spec: WorkflowSpec, context: WorkflowSyncContext): Promise<WorkflowSyncResult>;
+    /**
+     * Brings the workflow's owned trigger rows in line with its spec.
+     *
+     * A trigger the spec no longer names has its owned row **disabled rather than deleted**. Deleting
+     * would destroy the run history attached to it, and a workflow whose schedule someone removed by
+     * mistake should be recoverable — the row carries counts, last-run and next-run that are the only
+     * record that it ever fired.
+     */
+    private reconcileTriggers;
+    /** Identity of a schedule within a workflow — cron plus zone, matching `TriggerKey`. */
+    private scheduleKey;
+    /** The same identity, read back off a persisted job. */
+    private scheduleKeyOf;
+    /**
+     * Binds an entity-change trigger by creating the Entity Action rows the save pipeline already
+     * reads.
+     *
+     * Nothing here teaches the platform a new trick. `HandleEntityActions` has fired entity actions
+     * from the save pipeline all along; what was missing was a row saying "when an Invoice is
+     * updated, run Execute Agent with this agent". Three rows express that: the `EntityAction`
+     * (which entity, which action), the `EntityActionInvocation` (which change fires it), and an
+     * `EntityActionParam` carrying the agent to run.
+     *
+     * Idempotent by lookup rather than by delete-and-recreate: re-saving a workflow must not detach
+     * and re-attach a live trigger, because a change landing in that window would be missed.
+     *
+     * **Scope reconciles onto the binding's own `ScopeEntityID`/`ScopeRecordID`.** Those columns and
+     * the engine's scope resolver already exist for exactly this; leaving them unset while the spec
+     * declared a scope produced a workflow firing on every record of the entity while its author
+     * believed it was watching one. `filter` reconciles the same way — onto an `ActionFilter` bound
+     * through `EntityActionFilter`, the row the invocation path already consults.
+     */
+    private reconcileEntityEvent;
+    /**
+     * Brings the binding's filter row in line with the trigger's predicate.
+     *
+     * The trigger's `filter` is an expression; what the platform evaluates is an `ActionFilter.Code`
+     * bound through `EntityActionFilter`. That indirection is what lets a workflow narrow *when* it
+     * fires without the workflow layer inventing an evaluator of its own — `RunSingleFilter` already
+     * compiles, caches and fail-closes this code, and the change context it hands the expression is
+     * the same one every other entity action sees.
+     *
+     * **Removing a filter disables the binding rather than deleting the row.** The `ActionFilter`
+     * survives with its code intact, so re-adding the predicate is recoverable and the audit trail of
+     * what this trigger used to be narrowed by does not evaporate on a save. A `Disabled` binding is
+     * genuinely inert — {@link EntityActionInvocationSingleRecord.ResolveFilters} skips it, which
+     * matters because filters fail closed, so a disabled-but-honored filter would not be a no-op, it
+     * would be a permanent block.
+     */
+    private reconcileTriggerFilter;
+    /**
+     * Writes the filter row holding the generated predicate.
+     *
+     * Reuses the row the binding already points at, so editing a workflow's filter edits one row
+     * rather than accumulating an orphan per save. `UserDescription` keeps the author's expression
+     * verbatim next to the generated code — without it, reading the row back tells you what the
+     * machine produced but not what the person asked for.
+     */
+    private upsertActionFilter;
+    /**
+     * Turn the spec's scope names into the IDs the binding stores.
+     *
+     * A scope that names an entity the instance does not have is an error rather than a silent
+     * widening: "watch this one invoice" degrading to "watch every invoice" is the failure the
+     * scope columns exist to prevent.
+     */
+    private resolveScope;
+    /**
+     * Finds or creates the Entity Action binding this workflow needs.
+     *
+     * **Each workflow owns its own binding row.** `Execute Agent` is one shared action, so every
+     * workflow watching a given entity would otherwise land on the same `(EntityID, ActionID)` pair
+     * — and reusing that row means rewriting its `AgentID`, which silently repoints the first
+     * workflow's trigger at the second workflow's agent. Workflow A keeps looking configured, keeps
+     * showing its trigger, and never runs again.
+     *
+     * That shape was briefly impossible: `UQ_EntityAction_ActionID_EntityID`, added by the v5.37.x
+     * junction sweep, permitted one binding per (entity, action). The sweep's own stated scope was
+     * "pure junction tables ... with no other meaningful data columns", which `EntityAction` — with
+     * Status, Sequence, LoggingMode, scope columns and three owned child collections — never met.
+     * `V202608080100__v6.1.x__Drop_EntityAction_Uniqueness` removes it, which also unblocks the
+     * ordinary case of one action bound to one entity at two different events with different params.
+     *
+     * Ownership is therefore matched on the agent and the scope, not on entity + action alone.
+     */
+    private upsertEntityAction;
+    /**
+     * This workflow's own binding at this scope, if it already has one.
+     *
+     * Ownership lives in the `AgentID` param rather than on the binding row, so candidates are
+     * narrowed in SQL by entity + action + scope and then matched on that param. Scope is part of
+     * the identity because narrowing a trigger to a different record is a *different* subscription,
+     * not an edit of the existing one — matching without it would silently re-point the old binding.
+     */
+    private findOwnedEntityAction;
+    /** Finds or creates the invocation row that says which change fires the action. */
+    private upsertInvocation;
+    /**
+     * Finds or creates one Entity Action Param binding.
+     *
+     * `value` is null for value types the platform derives at invocation time (`Entity Object Data`,
+     * `Entity Object`, `Entity Field`) — for those the ValueType *is* the instruction.
+     */
+    private upsertActionParam;
+    private resolveJobTypeID;
+    /**
+     * Finds the Scheduled Jobs this workflow owns.
+     *
+     * Matched on a marker inside `Configuration` rather than on name, so renaming a workflow does not
+     * orphan its schedule and leave a second one firing alongside the new row.
+     */
+    private findOwnedJobs;
+    /** Creates or updates one owned Scheduled Job so it matches the trigger. */
+    private upsertScheduledJob;
+}
+//# sourceMappingURL=WorkflowSpecSync.d.ts.map

package/dist/WorkflowSpecSync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkflowSpecSync.d.ts","sourceRoot":"","sources":["../src/WorkflowSpecSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,iBAAiB,EAAgC,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAejG,OAAO,EAOH,KAAK,YAAY,EACpB,MAAM,8BAA8B,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,UAAU,CAAC;AAE7C,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAUpD,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG;IAC9B,WAAW,EAAE,QAAQ,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;CAC/B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAC9B,2EAA2E;IAC3E,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvF,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,oGAAoG;IACpG,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,qBAAa,gBAAgB;IACb,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,GAAE,mBAAmB,GAAG,IAAW;IAE3E;;;;;;OAMG;IACU,OAAO,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgCnG;;;;;;;OAOG;YACW,iBAAiB;IA+C/B,wFAAwF;IACxF,OAAO,CAAC,WAAW;IAInB,wDAAwD;IACxD,OAAO,CAAC,aAAa;IAIrB;;;;;;;;;;;;;;;;;;OAkBG;YACW,oBAAoB;IAmDlC;;;;;;;;;;;;;;;OAeG;YACW,sBAAsB;IA4CpC;;;;;;;OAOG;YACW,kBAAkB;IA4BhC;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IASpB;;;;;;;;;;;;;;;;;OAiBG;YACW,kBAAkB;IA+BhC;;;;;;;OAOG;YACW,qBAAqB;IAoCnC,mFAAmF;YACrE,gBAAgB;IAgC9B;;;;;OAKG;YACW,iBAAiB;YA4CjB,gBAAgB;IAkB9B;;;;;OAKG;YACW,aAAa;IAkB3B,4EAA4E;YAC9D,kBAAkB;CAoCnC"}