@opencxh/domain 1.270.0 → 1.275.0

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

@@ -0,0 +1,42 @@
+/**
+ * Is what a rule wrote still standing?
+ *
+ * The feedback loop's first real signal, and it needs no new write path: every run already
+ * carries `priors` — the previous value of each field it wrote, plus the params it wrote them
+ * with — because undo needs exactly that. Asking the same question an hour later turns it into a
+ * measurement.
+ *
+ * **Why this matters more than an approval rate.** The trust ladder promotes on *observed
+ * unchanged approval*, and approving is a ritual — people click yes. A correction is a real
+ * objection, and so is an undo. An automatic action that could be reversed in one click and never
+ * is, is a stronger promotion signal than any approval percentage; a burst of corrections is an
+ * immediate demotion signal.
+ */
+export type RunOutcome = "kept" | "corrected" | "undone" | "unknown";
+/** The half of an action's prior this question needs. `before` is undo's business, not this one. */
+export interface OutcomePrior {
+    action: string;
+    params: Record<string, unknown>;
+    /** Which params were content — a field the subject owns — rather than addressing. */
+    fields: string[];
+}
+/**
+ * Which fields no longer hold what the action put there.
+ *
+ * Shared with the undo, deliberately: "changed since" decides both whether an undo may run and
+ * whether this run counts as corrected, and two definitions of that would eventually disagree —
+ * with the undo overwriting somebody's change while the measurement called it kept.
+ *
+ * A field the subject does not report at all (`undefined`) is **not** drift. That is a reader
+ * that did not return the column, not a person who changed it, and counting it would turn every
+ * thin read into a wave of false corrections.
+ */
+export declare function driftedFields(prior: OutcomePrior, current: Record<string, unknown> | undefined): string[];
+/**
+ * The outcome of one run.
+ *
+ * `unknown` when the subject cannot be read — it was deleted, or its kind has no reader. Kept
+ * apart from `kept` on purpose: "nobody objected" and "we could not look" are different facts,
+ * and folding the second into the first is how a trust ladder promotes on silence.
+ */
+export declare function runOutcome(priors: readonly OutcomePrior[], current: Record<string, unknown> | undefined, undoneAt?: number): RunOutcome;

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

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

package/dist/entities/rule/trigger-source.d.ts

@@ -0,0 +1,137 @@
+import { ToolCatalogEntry } from '../../platform/ai-tools';
+/**
+ * What kind of value sits at a field, so the builder knows which widget to draw and the
+ * comparison operators that make sense.
+ *
+ * No `object`: a rule compares a leaf. Offering a whole object as the left-hand side of `==`
+ * produces a condition that is never true and reads as if it should be.
+ *
+ * `string[]` is here for the same reason rather than being folded into `string`. Tags, labels and
+ * party keys are the most obvious things to write a rule about, and on an array only `in` means
+ * anything — `==` against one is the silent never-matches this whole seam exists to prevent.
+ */
+export type EventFieldType = "string" | "string[]" | "number" | "boolean" | "date";
+/** Operators that mean something for this kind of value. The builder offers no others. */
+export declare function opsForFieldType(type: EventFieldType): readonly string[];
+/** One choice for a field with a fixed or looked-up set of values. */
+export interface EventFieldOption {
+    value: string;
+    /**
+     * The label as the server could build it. For something an admin typed (a project status, an
+     * inbox) that is the text itself; for one of ours it is the already-resolved fallback.
+     */
+    label: string;
+    /**
+     * Translation key, for a value that is *ours* and therefore translatable.
+     *
+     * Same split as `ActivityPreview.snippet`/`snippetKey`, and for the same reason: the list is
+     * built once on a server that has no user language, while every reader has their own. The
+     * builder prefers this and falls back to `label`.
+     */
+    labelKey?: string;
+}
+/**
+ * One thing a rule can test, declared by the app that writes the row.
+ *
+ * **Why declared and not listed centrally.** A hand-written table of fields drifts from the
+ * payload it describes, and the drift is silent: a rule on a path that yields `undefined` never
+ * fires and says nothing about why. That already happened here once — `TRIGGER_VARS` exists
+ * because the picker offered `trigger.fromEmail` and `trigger.channel`, neither of which the
+ * engine ever filled. A central list for comms, work and sales would be that same table with
+ * three apps to drift from instead of one.
+ */
+export interface EventField {
+    /**
+     * Path under `subject`, dot-notated: `"priority"`, `"lastActivityPreview.text"`.
+     *
+     * Relative, because `subject` is where the owning app's row lands in the condition context
+     * (`matchRules` builds `{ event, subject }`) and repeating that prefix in every declaration is
+     * an invitation to get it wrong in one of them. {@link fieldVarPath} adds it, once.
+     */
+    path: string;
+    type: EventFieldType;
+    /** What a person calls this. The builder shows this; the path is never on screen. */
+    label: string;
+    /**
+     * A fixed set of values — the builder offers a dropdown instead of a free text field.
+     *
+     * For what the *app* defines (a priority, a direction, a status category). What the
+     * *organisation* defines goes through {@link lookup}, because it is data and not vocabulary.
+     */
+    values?: EventFieldOption[];
+    /**
+     * The values are organisation data: ask the declaring app via `/provider/triggers/options`.
+     *
+     * This exists so the builder needs no per-field knowledge. Today `ConditionBuilder` has a
+     * `topicOptions()` that recognises a topic *by field name* — one hard-coded exception, and
+     * the second one (inboxes, users, statuses, pipelines) makes it a pattern.
+     */
+    lookup?: string;
+}
+/**
+ * One event an app publishes, and what a rule can ask about its subject.
+ *
+ * `fields` is per event and not per app on purpose: the subject differs even within one app —
+ * comms hands over the interaction, work the item, sales the transaction.
+ */
+export interface EventDescriptor {
+    /** As the bus delivers it, app-prefixed: `"communication:activities:created"`. */
+    name: string;
+    /** What this event is, in the author's language: "Er komt een bericht binnen". */
+    label: string;
+    /**
+     * What the subject is. Also the key the undo reader uses to fetch current state, so a new
+     * subject kind needs a reader there before its runs can be undone.
+     */
+    subjectKind: string;
+    fields: EventField[];
+}
+/** What a `trigger-source` returns on `GET /provider/triggers/describe`. */
+export interface TriggerSourceDescription {
+    events: EventDescriptor[];
+}
+/** An event plus the app that answered for it — the merged catalog a builder reads. */
+export interface VocabularyEvent extends EventDescriptor {
+    /**
+     * From the runtime, never from a field inside the payload: that would let one app claim
+     * another's events. Same rule the rest of the fan-out helpers hold.
+     */
+    app: string;
+}
+/**
+ * Everything a builder needs to write a rule: what it can react to, and what it can do.
+ *
+ * Both halves in one answer because they are one question — "what is possible here" — and because
+ * they are read together on every builder render. The action half is the tool federation with the
+ * model taken out from in front; it is filtered to what a rule may actually use, so the builder
+ * never has to show something it would refuse to save.
+ */
+export interface RuleVocabulary {
+    events: VocabularyEvent[];
+    /** The actions a rule may use. Outward ones are absent, not disabled — see `validateActions`. */
+    actions: ToolCatalogEntry[];
+    /** Apps that declare the role but answered nothing. Silence is named, not hidden. */
+    degradedApps: string[];
+}
+/**
+ * The JSONLogic variable for a field: `subject.<path>`.
+ *
+ * One function so the builder, the templates and the declaration tests cannot disagree about the
+ * prefix. `matchRules` evaluates against `{ event, subject }`, and a condition written against
+ * the bare path silently compares `undefined`.
+ */
+export declare function fieldVarPath(field: Pick<EventField, "path">): string;
+/** The event with this name, or `undefined`. */
+export declare function findEvent(vocabulary: Pick<RuleVocabulary, "events">, name: string): VocabularyEvent | undefined;
+/**
+ * Which declared paths the real subject does not have.
+ *
+ * **This is the point of declaring fields near the code that writes them.** A declaration is only
+ * worth more than a central list if something holds it against reality, and this is that
+ * something: each app's test feeds a real row through and asserts the answer is empty.
+ *
+ * A path is "missing" when it resolves to `undefined` — absent, or running through a `null`.
+ * `null` itself counts as present: a cleared assignee is a value a rule can meaningfully test
+ * for, and treating it as missing would make every declaration fail on an empty row.
+ */
+export declare function missingFieldPaths(fields: readonly EventField[], subject: unknown): string[];

package/dist/entities/rule/trigger-source.test.d.ts

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

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

@@ -1,4 +1,5 @@
 import { OwnerScope } from '../scope/types';
+import { OutcomePrior, RunOutcome } from './outcome';
 /**
  * When something starts. One vocabulary for every executor.
  *
@@ -101,3 +102,46 @@ export interface RuleEvent {
     /** How many rule hops produced this event. Absent = zero, a genuine first cause. */
     depth?: number;
 }
+/** One line of a rule run log. `ok: false` is a step that did not land, not a rule that did not fire. */
+export interface RuleTraceEntry {
+    ruleId: string;
+    action?: string;
+    ok: boolean;
+    note: string;
+}
+/**
+ * What one action changed, captured when it ran — the params it was called with, which of those
+ * were content (a field the subject owns) rather than addressing, and those fields as they were.
+ * A key missing from `before` held nothing.
+ */
+export interface ActionPrior extends OutcomePrior {
+    /** The rule that ran this action. Empty for an undo replay. */
+    ruleId?: string;
+    before: Record<string, unknown>;
+}
+/** What an owning app's write path posts after a rule acted: one rule, one event. */
+export interface RuleRunRecord {
+    ruleId: string;
+    ruleName?: string;
+    eventName: string;
+    eventId: string;
+    subjectKind?: string;
+    subjectId?: string;
+    applied: number;
+    trace: RuleTraceEntry[];
+    priors: ActionPrior[];
+}
+/**
+ * One thing a rule did, once, as the run log stores it. Written only when something happened.
+ *
+ * `outcome` is stamped an hour after the fact; empty means "not judged yet", and `unknown` is
+ * deliberately not `kept` — "nobody objected" and "we could not look" are different facts.
+ */
+export interface RuleRun extends RuleRunRecord {
+    id: string;
+    undoneAt?: number;
+    undoneBy?: string;
+    outcome?: RunOutcome | "";
+    outcomeAt?: number;
+    createdAt?: number;
+}