@opencxh/domain 1.274.0 → 1.276.0

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

@@ -1,5 +1,7 @@
 import { ActingIdentity } from '../../platform/identity';
 import { ResourceRef } from '../../platform/resource';
+import { AssignmentControl } from '../assignment/types';
+import { Trigger } from '../rule/types';
 import { OwnerScope } from '../scope/types';
 /**
  * Playbooks — event-driven automation with AI steps. See docs/PLAYBOOKS.md.
@@ -7,41 +9,18 @@ import { OwnerScope } from '../scope/types';
  * Two execution forms, one contract: see {@link Decider}. Every step type in
  * {@link Step} is executed; there is no kind the executor refuses.
  */
-export type Autonomy = "suggest" | "auto";
-export type PlaybookTrigger = {
-    kind: "activity";
-    activityTypes: string[];
-    /** Channel kinds: "mail" | "chat" | "voice" (derived from the activity type). */
-    channels?: string[];
-    /** Specific channel ids (e.g. per mailbox). Matched against activity.channelId. */
-    channelIds?: string[];
-    filter?: unknown;
-    /**
-     * Wait this many milliseconds, then run **once** for the messages in that window
-     * instead of once per message. The run executes on the **newest** message; the ones
-     * in between are already covered by the conversation lookup step.
-     *
-     * Deliberately on the trigger, not in the memory layer: coalescing is a property of
-     * "how often do I want to react", not of what you remember.
-     */
-    debounceMs?: number;
-} | {
-    kind: "manual";
-}
 /**
- * Someone assigns work to this playbook's agent — the wake-up call of an **assignment**.
- *
- * Not a new mechanism: an assignment is already an activity, so the same gate delivers it.
- * The question the engine cannot answer itself — *is this for MY agent?* — is answered by
- * `Playbook.agentId`, not here: one place names the agent, because that field also decides
- * who the run acts as. Which kinds of work can be assigned is **declared** by the app that
- * owns them (`assignment-source` federation, see `./assignment.ts`), hence a loose id in
- * `targetKind` instead of a union here.
+ * How much a run may do on its own: ask before every write, ask only before a write that leaves
+ * the organisation, or ask nothing. Ordered from most to least careful.
  */
- | {
-    kind: "assignment";
-    targetKind: string;
-};
+export type Autonomy = "suggest" | "outward" | "auto";
+/**
+ * The arms of {@link Trigger} the playbook executor runs: an activity, a person, an assignment.
+ * One vocabulary; each executor names the part it runs (rules: `event` and `schedule`).
+ */
+export type PlaybookTrigger = Extract<Trigger, {
+    kind: "activity" | "manual" | "assignment";
+}>;
 export interface Guardrails {
     maxSteps?: number;
     maxToolCalls?: number;
@@ -96,14 +75,14 @@ export interface ForEachStep<S = Step> {
 }
 export interface LookupStep {
     type: "lookup";
-    /** "tool:<namespaced>" (Fase 1) or a local source ("interactions"/"tasks"). */
+    /** The read tool, `<app>__<name>`. */
     source: string;
     filter?: unknown;
     as: string;
 }
 export interface ActionStep {
     type: "action";
-    /** Local action ("task.create"/"interaction.set"/"notify.user") or "tool:<namespaced>" (Fase 1). */
+    /** The write tool, `<app>__<name>`. */
     action: string;
     params: Record<string, unknown>;
     autonomy?: Autonomy;
@@ -120,11 +99,11 @@ export interface ActionStep {
 /**
  * Wait until this task is done. Counterpart of `wait-for-reply`, for the support-procedure
  * case "a colleague must do something: create a task and wait for it". `taskId` is an
- * ordinary reference, e.g. `$newTask.id` after a `create_task` with an `as`.
+ * ordinary reference, e.g. `{{newTask.id}}` after a `create_task` with an `as`.
  */
 export interface WaitForTaskStep {
     type: "wait-for-task";
-    /** `$ref` or literal id of the task to wait on. */
+    /** `{{ref}}` or literal id of the task to wait on. */
     taskId: string;
 }
 /**
@@ -145,7 +124,7 @@ export interface ClassifyStep {
     fields?: unknown;
     instruction?: string;
     /**
-     * Which text is classified, as a `$ref` into the run vars. Default `$trigger.text`.
+     * Which text is classified, as a `{{ref}}` into the run vars. Default `{{trigger.text}}`.
      * Needed when the trigger carries no text: an `INTERACTION_STATUS_CHANGED` activity has
      * only `{ fromStatus, toStatus }`, so `trigger.text` is empty. With `input: "$thread"` the
      * step reads what an earlier `lookup` fetched.
@@ -217,6 +196,8 @@ export interface ParallelStep<S = Step> {
     onBranchError?: "fail" | "continue";
 }
 export type Step = ConditionStep | ForEachStep | ParallelStep | LookupStep | ActionStep | ClassifyStep | GenerateStep | AgentStep | WaitForReplyStep | WaitForTaskStep;
+/** Every step type, once. The `satisfies` pair fails to compile when a type is added or dropped. */
+export declare const STEP_TYPES: readonly ["condition", "for-each", "parallel", "lookup", "action", "classify", "generate", "agent", "wait-for-reply", "wait-for-task"];
 /**
  * A **procedure**: how a scenario is handled, as prose with guardrails. The second execution
  * form next to `Step[]`; {@link AgentStep} is its inside-a-flow variant (it *contains* one).
@@ -477,6 +458,11 @@ export interface PlaybookRun {
     subjectKind?: string;
     subjectId?: string;
     status: RunStatus;
+    /**
+     * The autonomy this run started with ({@link resolveAutonomy}), frozen: a resume after an
+     * approval runs at the same setting it parked with. Absent on runs from before this field.
+     */
+    autonomy?: Autonomy;
     /**
      * The cause: which signal started this run, plus the input as it looked **then**.
      *
@@ -522,6 +508,12 @@ export interface PlaybookRun {
     }[] | null;
     /** The AI_ACTION_PROPOSED activity created for the current pending batch (for resolve on approve/reject). */
     proposalActivityId?: string | null;
+    /** The approval request a parked run waits on (`runApprovalKey`). */
+    approvalRequestId?: string | null;
+    /** Every request this park waits on, one per distinct act; resumes when all are approved. */
+    approvalRequestIds?: string[];
+    /** The move an assignment turn chose before it parked; restored when the turn resumes. */
+    turnControl?: AssignmentControl | null;
     /**
      * What this run waits for, when `status === "waiting"`. `null` when cleared (the store
      * writes `null`), absent on a run that is not waiting. A new wait reason costs a member in

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

@@ -67,9 +67,14 @@ export interface ReactionChange {
     actor: ReactionActor;
     /** `true` put it there, `false` took it away. */
     on: boolean;
+    /**
+     * The signed-in user who clicked. Absent when an app wrote it (a provider sync carrying a
+     * Teams emoji across), so a listener that syncs out never echoes a mirrored reaction back.
+     */
+    byUser?: string;
 }
 /**
- * The `reactions:changed` event, as apps receive it (`communication:reactions:changed`).
+ * The `reactions:changed` event, as apps receive it (`context:reactions:changed`).
  *
  * Carries **both** the resulting chip set and the delta, because the two consumers need
  * different things. A feed re-renders from `reactions` — a client that only got deltas and

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

@@ -0,0 +1,23 @@
+/**
+ * One variable language for rules and playbooks: `{{path}}`.
+ *
+ * A value that is *only* a reference keeps the referenced value's type (`"{{subject.id}}"` → the
+ * id, a number stays a number); a reference inside longer text is stringified, objects as JSON.
+ * `{ "var": "path" }` in a condition is json-logic's own and not handled here.
+ *
+ * What an unknown reference becomes is the executor's call:
+ * - `"empty"` (rules): `""` — the same "empty is not an instruction" the tools already read;
+ * - `"throw"` (playbooks): an error when the path's **root** is not there (a typo, or a step that
+ *   never ran). A known root with an empty leaf stays empty: a chat message has no `subject`, and
+ *   that is not a mistake.
+ */
+export interface BindOptions {
+    onMissing?: "empty" | "throw";
+    /** Where the value sits, for the error message. */
+    where?: string;
+}
+export declare class UnresolvedRefError extends Error {
+    constructor(message: string);
+}
+export declare function bindParams(params: Record<string, unknown>, context: Record<string, unknown>, options?: BindOptions): Record<string, unknown>;
+export declare function bindValue(value: unknown, context: Record<string, unknown>, options?: BindOptions): unknown;

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

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

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

@@ -0,0 +1,40 @@
+/**
+ * Does this cron expression name this minute?
+ *
+ * Five fields, standard order: `minute hour day-of-month month day-of-week`. Each field is `*`,
+ * a number, a range (`a-b`), a step (`*` slash `n`), or a comma-separated list of those.
+ *
+ * **Hand-written and not a library.** It is thirty lines, it has to run inside QuickJS, and the
+ * alternative is a dependency in `packages/domain` — which carries none, on purpose. What it
+ * deliberately does **not** support is the part of cron nobody writes by hand: `L`, `W`, `#`,
+ * named months and weekdays, and seconds. An expression using one of those is refused rather
+ * than quietly matching nothing, which is the failure mode a scheduled rule cannot afford — a
+ * rule that never fires looks exactly like a rule whose condition is never true.
+ */
+export interface ParsedCron {
+    minute: Set<number>;
+    hour: Set<number>;
+    dayOfMonth: Set<number>;
+    month: Set<number>;
+    dayOfWeek: Set<number>;
+    /** True when either day field was left as `*` — see {@link cronMatches}. */
+    anyDayOfMonth: boolean;
+    anyDayOfWeek: boolean;
+}
+/** `null` when the expression is not one this matcher can honour. */
+export declare function parseCron(expression: string): ParsedCron | null;
+/** Is this expression one this matcher can honour at all? */
+export declare function isSupportedCron(expression: string): boolean;
+/**
+ * Does this expression name the minute `date` falls in?
+ *
+ * The day rule is cron's one genuine oddity and it is kept: when **both** day fields are
+ * restricted they are OR-ed, not AND-ed — `0 9 1 * 1` means "the first of the month, and every
+ * Monday", not "a Monday that is the first". Every cron implementation does this, and quietly
+ * doing the intuitive thing instead would make a rule fire on a handful of days a year.
+ *
+ * Evaluated in **UTC**, because that is what the tick that calls it runs in. A rule author who
+ * means nine in the morning in Amsterdam writes the UTC hour; naming a timezone per rule is a
+ * field this type does not have yet, and guessing the organisation's is worse than the omission.
+ */
+export declare function cronMatches(expression: string, date: Date): boolean;

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

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

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

@@ -0,0 +1,31 @@
+import { EvalCase, EvalCaseResult } from '../eval/types';
+import { Rule, RuleEvent } from './types';
+/**
+ * The first eval suite, and the one that is free: **does this rule set do what its author said?**
+ *
+ * Deterministic, no model, no network — which is what makes it the suite that belongs in CI. The
+ * whole question is whether `matchRules` plus a condition produces the actions somebody expected,
+ * and every part of that is already pure.
+ *
+ * This is the check that would have caught the shipped starter template pointing at
+ * `subject.lastActivityPreview.text`: a field no conversation has, so the rule compared
+ * `undefined`, never fired, and said nothing about why. It was found by hand, once. A case says
+ * "this event, this rule, these actions" and it stays found.
+ */
+export interface RuleCaseInput {
+    event: RuleEvent;
+    rules: Rule[];
+}
+export interface RuleCaseExpected {
+    /** The actions that should fire, in order. An empty list means "this must not fire". */
+    actions: string[];
+}
+export type RuleEvalCase = EvalCase<RuleCaseInput, RuleCaseExpected>;
+/**
+ * Judge one rule case.
+ *
+ * The evaluator is injected and the caller is expected to pass **the production one**. A suite
+ * with its own condition semantics measures its own semantics; the point is to measure what will
+ * actually run.
+ */
+export declare function judgeRuleCase(testCase: RuleEvalCase, evaluate: (condition: unknown, context: Record<string, unknown>) => boolean): EvalCaseResult;

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

@@ -1,4 +1,8 @@
+export * from './bind';
 export * from './condition';
+export * from './cron';
+export * from './eval';
 export * from './match';
+export * from './outcome';
 export * from './trigger-source';
 export * from './types';

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

@@ -1,4 +1,12 @@
 import { Rule, RuleEvent } from './types';
+/**
+ * The event name a clock tick carries.
+ *
+ * A reserved name and not a kind of its own, so the tick travels through the same matcher, the
+ * same guards and the same idempotency key as everything else. `@` cannot occur in an
+ * `<app>:<resource>:<verb>` name, so no app can ever deliver it by accident.
+ */
+export declare const SCHEDULE_EVENT = "@schedule";
 /**
  * How deep a chain of rules may go before it is refused.
  *

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

@@ -0,0 +1,44 @@
+/**
+ * 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[];
+    /** Fields the tool reported writing with a value it chose itself (`AiToolResult.wrote`). */
+    wrote?: Record<string, unknown>;
+}
+/**
+ * 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

@@ -1,4 +1,5 @@
 import { ToolCatalogEntry } from '../../platform/ai-tools';
+import { RuleTemplate } from './types';
 /**
  * What kind of value sits at a field, so the builder knows which widget to draw and the
  * comparison operators that make sense.
@@ -79,16 +80,15 @@ export interface EventDescriptor {
     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.
-     */
+    /** What the subject is, for the builder. The run itself records the subject's scope kind. */
     subjectKind: string;
     fields: EventField[];
 }
 /** What a `trigger-source` returns on `GET /provider/triggers/describe`. */
 export interface TriggerSourceDescription {
     events: EventDescriptor[];
+    /** Rules to start from, on this app's own events. */
+    templates?: RuleTemplate[];
 }
 /** An event plus the app that answered for it — the merged catalog a builder reads. */
 export interface VocabularyEvent extends EventDescriptor {

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

@@ -1,11 +1,13 @@
 import { OwnerScope } from '../scope/types';
+import { OutcomePrior, RunOutcome } from './outcome';
 /**
  * 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.
+ * Playbooks now run a subset of this union (`PlaybookTrigger`); webhooks store `event` names.
  *
- * **Four arms, not five.** `stream` is deliberately absent. It existed once, as a field-less
+ * **No `stream` arm.** `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
@@ -26,18 +28,42 @@ export type Trigger =
  | {
     kind: "manual";
 }
-/** Work was handed to an agent. `targetKind` is declared by the app that owns that work. */
+/**
+ * Work was handed to an agent. `targetKind` is declared by the app that owns that work
+ * (`assignment-source` federation, see `playbook/assignment.ts`); which agent is answered by
+ * `Playbook.agentId`, not here.
+ */
  | {
     kind: "assignment";
     targetKind: string;
+}
+/**
+ * A message appears: these activity types, optionally on these channel kinds or ids, passing
+ * `filter` (JSONLogic). Its own arm rather than an `event` with a filter, so the editor keeps
+ * its pickers instead of an expression.
+ */
+ | {
+    kind: "activity";
+    activityTypes: string[];
+    /** Channel kinds: "mail" | "chat" | "voice" (derived from the activity type). */
+    channels?: string[];
+    /** Specific channel ids (e.g. per mailbox). Matched against activity.channelId. */
+    channelIds?: string[];
+    filter?: unknown;
+    /**
+     * Wait this many milliseconds, then run **once** for the messages in that window instead
+     * of once per message, on the newest one. Deliberately on the trigger: coalescing is
+     * "how often do I react", not what you remember.
+     */
+    debounceMs?: number;
 };
 /**
  * One thing a rule does.
  *
- * **`action` is always `tool:<namespaced>`.** The action library is the tool federation — the
+ * **`action` is `<app>__<tool>`** — 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.
+ * `effect` classification and an approval hook. Playbooks spell it the same.
  */
 export interface RuleAction {
     action: string;
@@ -101,3 +127,64 @@ 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;
+}
+/**
+ * A rule an organisation can start from, declared by the app whose event it listens to.
+ *
+ * Data, not rows seeded on install: an organisation that never opens the builder should not
+ * acquire automation it did not ask for. Installing one is a normal create, so it lands disabled
+ * and passes the same save-time gate as anything a person writes.
+ */
+export interface RuleTemplate {
+    id: string;
+    name: string;
+    description: string;
+    /** What the author still has to fill in. Named, so the form can ask instead of guessing. */
+    blanks: {
+        path: string;
+        label: string;
+    }[];
+    rule: Pick<Rule, "trigger" | "when" | "then">;
+}

package/dist/entities/scope/actor.d.ts

@@ -7,10 +7,5 @@ import { OwnerScope } from './types';
  * carries an id on one side and not on the other. This is that translation, and it is
  * meant to be the only one: a hand-rolled `kind === "personal" ? "user" : …` at a call
  * site is how two vocabularies for the same three rungs drift apart.
- *
- * It arrived as `playbookActor` in `entities/playbook/`, whose own docstring already
- * claimed to be "the only place this belongs" — correct, but it read as
- * playbook-specific while every scoped entity needs the same conversion. `playbookActor`
- * stays as a name so the playbook call sites and their tests keep working.
  */
 export declare function toActingIdentity(scope: OwnerScope): ActingIdentity;

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

@@ -50,7 +50,7 @@ export interface SlaTarget {
 }
 /**
  * A named set of service targets. Assigned to a resource explicitly — from a workflow rule
- * (`tool:context__apply_sla`) or by hand — never matched automatically. That is why there is
+ * (`context__apply_sla`) or by hand — never matched automatically. That is why there is
  * no `appliesTo` and no `order`: both only exist to drive a matcher nothing calls.
  */
 export interface SlaProfile {

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

@@ -5,7 +5,13 @@
  */
 export type WebhookMethod = "POST" | "PUT";
 export type WebhookContentType = "json" | "multipart";
-export type WebhookTrigger = "interactions:created" | "interactions:updated" | "activities:created" | "activities:updated";
+/**
+ * The bus events a webhook can listen to — full names, the same string as a rule's
+ * `Trigger.event.name`. Add one here and the automations app subscribes to it.
+ */
+export declare const WEBHOOK_EVENTS: readonly ["communication:interactions:created", "communication:interactions:updated", "communication:activities:created", "communication:activities:updated"];
+export type WebhookTrigger = (typeof WEBHOOK_EVENTS)[number];
+export declare function isWebhookEvent(value: unknown): value is WebhookTrigger;
 export interface Webhook {
     id: string;
     organizationId: string;