@opencxh/domain 1.265.1 → 1.270.0

package/dist/entities/rule/index.d.ts

@@ -0,0 +1,2 @@
+export * from './match';
+export * from './types';

package/dist/entities/rule/match.d.ts

@@ -0,0 +1,49 @@
+import { Rule, RuleEvent } from './types';
+/**
+ * How deep a chain of rules may go before it is refused.
+ *
+ * A rule writes, a write is an event, an event triggers rules. Async that is a slow loop; **in a
+ * write path it is a stack**, and it takes down the request that started it. Three hops is enough
+ * for anything anyone meant to build and short enough that a mistake stops being one.
+ */
+export declare const MAX_RULE_DEPTH = 3;
+/** A rule that fires, with the key that makes firing it twice a no-op. */
+export interface RuleMatch {
+    rule: Rule;
+    /**
+     * `<eventId>:<ruleId>:<version>`. A write path can run again — a retry, a redelivery — and the
+     * effect must land once. The version is in there on purpose: against an edited rule the same
+     * event is a different decision, and that one is allowed to happen.
+     */
+    idempotencyKey: string;
+}
+export interface RuleMatchResult {
+    matched: RuleMatch[];
+    /**
+     * Why each rule that did not fire did not fire, in words.
+     *
+     * The same reason `triggerMismatch` returns a sentence rather than a boolean: "why did nothing
+     * happen" is the question an admin actually asks, and a silent empty list is the worst possible
+     * answer to it.
+     */
+    skipped: {
+        ruleId: string;
+        reason: string;
+    }[];
+}
+/**
+ * Which rules fire for this event.
+ *
+ * Pure, and the evaluator is injected — `packages/domain` carries no dependencies, and the
+ * JSONLogic implementation lives with the executor. That also makes every guard below testable
+ * without a store, which is the point: each one is a rule about *not* doing something, and those
+ * are exactly the ones nobody notices are broken.
+ */
+export declare function matchRules(event: RuleEvent, rules: readonly Rule[], evaluate: (condition: unknown, context: Record<string, unknown>) => boolean): RuleMatchResult;
+/**
+ * The event a rule's own write produces, stamped so the guards above can see it coming.
+ *
+ * One function so no call site has to remember both fields: forgetting `depth` makes the ceiling
+ * unreachable, and forgetting `causedByRule` makes a rule able to answer itself.
+ */
+export declare function causedBy(event: RuleEvent, ruleId: string): Pick<RuleEvent, "causedByRule" | "depth">;

package/dist/entities/rule/match.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/rule/types.d.ts

@@ -0,0 +1,103 @@
+import { OwnerScope } from '../scope/types';
+/**
+ * When something starts. One vocabulary for every executor.
+ *
+ * There were five of these, and they had to agree without anything saying so: `PlaybookTrigger`,
+ * `webhook.triggers[]` (four fixed strings), the sync tick, and twenty-one hand-rolled cron jobs.
+ *
+ * **Four arms, not five.** `stream` is deliberately absent. It existed once, as a field-less
+ * `{ kind: "stream" }` on `PlaybookTrigger`, and was removed with a reason that generalises:
+ * *"Definitions belong separated by their runtime, not by their editor."* A live read lane has no
+ * run, no lock and no gate, so it is not an automation with a trigger — it is its own thing
+ * (`LiveLens`), and it carries its cadence itself.
+ */
+export type Trigger = 
+/** Something happened. `name` is what the bus delivers: `<app>:<resource>:<verb>`. */
+{
+    kind: "event";
+    name: string;
+}
+/** The clock. */
+ | {
+    kind: "schedule";
+    cron: string;
+}
+/** A person pressed start. */
+ | {
+    kind: "manual";
+}
+/** Work was handed to an agent. `targetKind` is declared by the app that owns that work. */
+ | {
+    kind: "assignment";
+    targetKind: string;
+};
+/**
+ * One thing a rule does.
+ *
+ * **`action` is always `tool:<namespaced>`.** The action library is the tool federation — the
+ * same 62 descriptors the assistant uses, with the model taken out from in front. A second
+ * library would duplicate what a descriptor already carries: a JSON-Schema, a scope gate, an
+ * `effect` classification and an approval hook.
+ */
+export interface RuleAction {
+    action: string;
+    params: Record<string, unknown>;
+}
+/**
+ * *If this, then that* — without a model.
+ *
+ * The deterministic kind of automation. Seven table-stakes gaps have this exact shape (routing,
+ * auto-assign on inbound, binding an SLA profile, escalation, a macro that does more than paste
+ * text, status rules in work, "quote accepted so the deal is won"), and none of them needs a
+ * model. Today every one of them would have to go through an LLM turn.
+ *
+ * What makes it a *rule* and not a workflow is the executor, not the shape: a rule runs
+ * synchronously in the write path of the app that owns the subject, so a conversation is routed
+ * and assigned **before** it becomes visible rather than jumping a beat later.
+ */
+export interface Rule {
+    id: string;
+    organizationId: string;
+    ownerScope: OwnerScope;
+    name: string;
+    /** What this rule is for, in the author's own words. */
+    description?: string;
+    enabled: boolean;
+    /**
+     * Only `event` runs today. The other arms exist because the vocabulary is shared; a rule on a
+     * schedule waits for the cadence work in a later wave.
+     */
+    trigger: Trigger;
+    /**
+     * JSONLogic over `{ event, subject }` — **and nothing else**. Absent = always.
+     *
+     * That the context is only those two is the load-bearing constraint, not an omission. Give a
+     * rule a fan-out ("is this customer a VIP", "how many open items has this team") and the write
+     * path of every inbound message becomes as slow as the slowest app that answers — and then the
+     * whole reason it runs synchronously is gone. Anything needing a lookup is a workflow.
+     */
+    when?: unknown;
+    then: RuleAction[];
+    /**
+     * Bumped on every edit. Part of the idempotency key: re-running an event against an edited
+     * rule is a different decision, and should be allowed to happen once.
+     */
+    version: number;
+}
+/** What a rule is offered. The event, the row it is about, and where it came from. */
+export interface RuleEvent {
+    /** `<app>:<resource>:<verb>`, as the bus delivers it. */
+    name: string;
+    /** Stable id of this occurrence. Half of the idempotency key. */
+    id: string;
+    payload: Record<string, unknown>;
+    /** The row this is about, as the owning app already has it in hand. */
+    subject?: Record<string, unknown>;
+    /**
+     * Set when this event was itself produced by a rule. Both halves of the re-entrancy guard
+     * hang off this: a rule may not react to its own output, and a chain has a ceiling.
+     */
+    causedByRule?: string;
+    /** How many rule hops produced this event. Absent = zero, a genuine first cause. */
+    depth?: number;
+}