@volter/supercode-orchestrator 0.4.80 → 0.4.81

package/ontology.d.ts

@@ -20,6 +20,17 @@ export type AccessPolicy =
   /** Anyone. */
   | 'open';
 
+/**
+ * One step a transition, an entry or an exit takes: a primitive the engine provides, named, with its arguments
+ * (`notify: {roles: [creator], template: …}`). Written as a one-key map.
+ */
+export interface Action {
+  /** The primitive (`assign`, `count`, `reset`, `notify`, `comment`, `send_to_actor`, `close_session`, …). */
+  name: string;
+  /** Its arguments, as written. */
+  args: unknown;
+}
+
 /** What one artifact reached on the way in or out. */
 export interface ArtifactFidelity {
   /** Path relative to the home the codec read or wrote. */
@@ -90,6 +101,45 @@ export interface ChannelConfig {
   extra?: Record<string, unknown>;
 }
 
+/** A transition taken once a duration has passed in the status (XState's `after`, ASL's `Wait`). */
+export interface Delayed {
+  /** How long, in seconds (an expression). */
+  after: Expr;
+  /** Source statuses; empty applies from every status. */
+  from?: string[];
+  /**
+   * Who may send the event: role names (the workflow's `roles`, and the engine's `platform` and `manager`).
+   * Empty: anyone who may write the card.
+   */
+  by?: string[];
+  /** The transition is taken only when this holds (Jira's condition); the first one that holds is taken. */
+  guard?: Expr | null;
+  /** Must hold, else the event is refused with the message (Jira's validator). */
+  validate?: Validation[];
+  /** The status the card moves to: a status name, or `{{expr}}`; none stays where it is (runs the actions only). */
+  target?: string | null;
+  /** What happens, in order, after the move (Jira's post functions). */
+  actions?: Action[];
+  /** What a person reads about it (the event's door text, the log). */
+  description?: string | null;
+}
+
+/** The dispatcher: when it runs, what it may start, in what order, under which caps. */
+export interface Dispatch {
+  /** Whether the served home dispatches its boards (an expression; Hermes's `dispatch_in_gateway`). */
+  serve?: Expr | null;
+  /** Seconds between ticks. */
+  tick: Expr;
+  /** The event the dispatcher sends a card it starts (to cards whose status has a transition for it). */
+  start: string;
+  /** Which cards it may start this tick. */
+  eligible?: Expr | null;
+  /** The order it starts them in: sort keys, `-` before one for descending. */
+  order?: Expr[];
+  /** The caps. */
+  limits?: Limit[];
+}
+
 /** Why a binding ended (`docs/ORCHESTRATOR-IR.md` §2.5). */
 export type EndReason =
   /** Idle expiry. */
@@ -112,6 +162,13 @@ export type EnvValue =
   /** A secret, named and never held. */
   | SecretRef;
 
+/**
+ * An expression over the card, its relations, the event and `params` (a small CEL-like language: literals,
+ * `card.*`, `event.*`, `params.*`, comparisons, `&&`/`||`/`!`, `in`, and the engine's functions such as
+ * `parents.all(p, …)`). Written as a string; a bare number, boolean or null is the literal it spells.
+ */
+export type Expr = string;
+
 /**
  * How faithfully a reconstruction reproduces its source.
  *
@@ -241,6 +298,20 @@ export interface JobOrigin {
   thread_id?: string | null;
 }
 
+/** A cap on what the dispatcher starts: cards counted per group, at most `max` in each. */
+export interface Limit {
+  /** What the cap is about, for its message. */
+  description?: string | null;
+  /** The group a card falls in (GitHub's `concurrency.group`): `'home'`, `card.board`, `card.assignee`, … */
+  group: Expr;
+  /** Which cards count against it. */
+  counts: Expr;
+  /** The cap; a cap that evaluates to nothing caps nothing. */
+  max: Expr;
+  /** Slots held back for the cards this matches while any waits (Hermes's review reservation). */
+  reserve?: Reserve | null;
+}
+
 /** One delivery obligation. */
 export interface Obligation {
   /** The id. */
@@ -300,6 +371,8 @@ export interface Orchestration {
   root: string;
   /** `default` is the root folder; the rest are `profiles/<name>/`. */
   profiles: Record<string, Profile>;
+  /** O — how the home's boards are worked (`workflow.yaml` at the root; Hermes's dispatcher when there is none). */
+  workflow?: Workflow;
 }
 
 /** What is delivered. */
@@ -414,6 +487,14 @@ export interface Repeat {
   completed?: number;
 }
 
+/** Slots of a limit held for some cards. */
+export interface Reserve {
+  /** The cards the slots are held for. */
+  for: Expr;
+  /** How many. */
+  slots: Expr;
+}
+
 /** Unmodeled source fields, keyed by the source's own field name. */
 export type Residue = Record<string, unknown>;
 
@@ -441,6 +522,49 @@ export interface RouteMatch {
   thread_id?: string | null;
 }
 
+/** What runs while a card is in a status: an actor of a role's lane in a named session slot of the card. */
+export interface Run {
+  /** The role whose lane (the profile it names) runs it. */
+  role: string;
+  /**
+   * The card's session slot it runs in: a live session in the slot is kept, a lost one resumed, an empty slot
+   * started fresh. Different slots are different sessions (a reviewer never works in the implementer's).
+   */
+  session: string;
+  /**
+   * What the actor is told when it starts: a template over the card (`{{card.id}}`, `{{context}}`) and
+   * `{{doors}}`, the events the actor may send in this status, generated from its transitions.
+   */
+  prompt?: string;
+  /** Prompt file relative to the orchestration home. */
+  prompt_file?: string | null;
+  /** Skills the actor's session is given. */
+  skills?: string[];
+  /**
+   * Limits on the run, each an expression in seconds or a count (`runtime`, `heartbeat`, …); the engine emits
+   * an event when one passes (`timed_out`, `stale`, …).
+   */
+  limits?: Record<string, Expr>;
+}
+
+/** The independently supervised run machine. Its events never become card notices. */
+export interface RunMachine {
+  /** Run specification selected for a card with an Every interval. */
+  recurring_role?: string | null;
+  /** Shared supervision limits, overridden by individual role specifications. */
+  limits?: Record<string, Expr>;
+  /** Named run specifications, selected by a card status or a recurring role. */
+  roles?: Record<string, Run>;
+  /** Run states and their entry, exit and event rules. */
+  states?: Record<string, Status>;
+  /** Initial run state. */
+  initial?: string;
+  /** Supervision shared by all run states. */
+  on?: Record<string, Transition[]>;
+  /** A run outcome emits this card verb (the sole link between machines). */
+  outcomes?: Record<string, Transition[]>;
+}
+
 /** When a job fires. */
 export type Schedule =
   /** Once, at an instant. */
@@ -457,6 +581,39 @@ export type SecretRef =
   /** A key in the home's own `.env` file. */
   | { dotenv: string };
 
+/** One status a card can be in. */
+export interface Status {
+  /**
+   * What `kanban.db`'s `tasks.status` holds for a card here, so Hermes reads the board (Hermes's own nine
+   * statuses store as themselves); the exact name rides beside it where it differs.
+   */
+  stored_as?: string | null;
+  /** What a person reads about it. */
+  description?: string | null;
+  /** What runs while a card is here. */
+  run?: Run | null;
+  /** A specification in the run machine's roles, without repeating supervision. */
+  run_role?: string | null;
+  /** Status used when a failed or blocked run is later resumed. */
+  resume_as?: string | null;
+  /** Done on entering (after the move's own actions). */
+  entry?: Action[];
+  /** Done on leaving (before the move's own actions): e.g. `close_session: reviewer`. */
+  exit?: Action[];
+  /** Events and their transitions, the first whose guard holds taken. */
+  on?: Record<string, Transition[]>;
+  /** Transitions taken as soon as their guard holds (XState's `always`). */
+  always?: Transition[];
+  /** Transitions taken after a time in the status. */
+  after?: Delayed[];
+}
+
+/** Ordered lowering rule for Hermes's fixed dispatcher. */
+export interface StorageRule {
+  guard: Expr;
+  status: string;
+}
+
 /**
  * ORCH-3: the conversation identity on a surface. Full tuple on a channel;
  * degenerate (all `None`) on a terminal.
@@ -490,6 +647,27 @@ export type Target =
   /** A named surface, as `hermes send --to` spells one. */
   | { platform: string; chat_id?: string | null; thread_id?: string | null; kind: 'explicit' };
 
+/** A move from the card's status on an event (or on none: `always`, `after`). */
+export interface Transition {
+  /** Source statuses; empty applies from every status. */
+  from?: string[];
+  /**
+   * Who may send the event: role names (the workflow's `roles`, and the engine's `platform` and `manager`).
+   * Empty: anyone who may write the card.
+   */
+  by?: string[];
+  /** The transition is taken only when this holds (Jira's condition); the first one that holds is taken. */
+  guard?: Expr | null;
+  /** Must hold, else the event is refused with the message (Jira's validator). */
+  validate?: Validation[];
+  /** The status the card moves to: a status name, or `{{expr}}`; none stays where it is (runs the actions only). */
+  target?: string | null;
+  /** What happens, in order, after the move (Jira's post functions). */
+  actions?: Action[];
+  /** What a person reads about it (the event's door text, the log). */
+  description?: string | null;
+}
+
 /** ORCH-3: why a session exists (the trigger noun; `docs/HERMES-IDEAL-SUPPORT-DESIGN.md` §3). */
 export type Trigger =
   /** A person started it on a terminal, IDE, or chat surface. */
@@ -511,6 +689,14 @@ export type Trigger =
   /** The source does not say. */
   | 'unknown';
 
+/** A validator: the expression must hold, else the event is refused with the message. */
+export interface Validation {
+  /** What must hold. */
+  expr: Expr;
+  /** The refusal. */
+  message: string;
+}
+
 /** One subscription: the route is `/webhooks/<name>`. */
 export interface WebhookSubscription {
   /** The name. */
@@ -585,3 +771,42 @@ export type WorkerSurface =
    * when it cannot be resumed.
    */
   | 'pane';
+
+/** A board's workflow. */
+export interface Workflow {
+  /** The run machine; absent for legacy homes during migration. */
+  run?: RunMachine | null;
+  /** Card verbs declared once, with source statuses on each transition. */
+  verbs?: Record<string, Transition[]>;
+  /** Derived card conditions, such as ready. */
+  derived?: Record<string, Expr>;
+  /** Relation policies, interpreted by the engine's relation primitives. */
+  relations?: Record<string, unknown>;
+  /** Flag policies, interpreted by the engine's flag primitives. */
+  flags?: Record<string, unknown>;
+  /** Ordered Hermes projection and its explicitly accepted losses. */
+  stored_as?: StorageRule[];
+  losses?: string[];
+  /** What a person reads about it. */
+  description?: string | null;
+  /**
+   * Named values the expressions read (`params.failure_limit`); a home's config.yaml `kanban:` keys override
+   * them by name, so Hermes's settings are this workflow's parameters.
+   */
+  params?: Record<string, unknown>;
+  /** Who acts on a card, each an expression naming a profile (`implementer: card.assignee`) or a person. */
+  roles?: Record<string, Expr>;
+  /** Where a new card starts: the first transition whose guard holds. */
+  initial: Transition[];
+  /** Every status, by name. */
+  statuses: Record<string, Status>;
+  /** Events that apply in every status (a status's own `on` for the same event is tried first). */
+  on?: Record<string, Transition[]>;
+  /** The dispatcher. */
+  dispatch: Dispatch;
+  /**
+   * Who is told what: for each audience (`creator`, `worker`, `dependency`, `chat`: who a card's subscriptions
+   * are), the event kinds it hears and the template each is told in. A kind not named is not sent.
+   */
+  notify?: Record<string, Record<string, string>>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.4.80",
+  "version": "0.4.81",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {