Triggers (TriggerDecl)

Generated from the doc schema (CatalogDocSchema, @canonify/kernel-catalog/doc): each field’s type, default and description are the schema’s own, and each example is a bundle file that readBundle decodes. A field’s Example is its value in one of those examples.

TriggerDecl

A trigger: an accountable automatic action (runtime).

The triggers slot of the doc holds these, keyed by id. In a bundle each is one file, triggers/<name>.json, named by its name, which the file then leaves out.

Field	Type	Required	Default	Example	Description
`id`	TriggerId	yes (propose assigns it; a new declaration leaves it out)	—	—	A trigger id (`tr_…`); renames keep it.
`name`	Ident	yes	—	`"daily_reminder"`	The trigger name.
`declarer`	DeclarerRef	no	—	`{"account":"u-01HZY8Q2:person"}`	Who declared it, recorded by the catalog service at promote; an authored value is replaced (C35).
`on`	TriggerDecl.on	yes	—	`{"cadence":"daily at 07:00"}`	What fires the trigger: a cadence, a change, entering or leaving a state, or a refused call.
`select`	TriggerDecl.select	no	—	(see the example)	A cadence trigger runs the action once per selected row.
`run`	TriggerDecl.run	yes	—	`{"action":"ac_7t9w1y3a5c","input":{"order":"this"}}`	The call it makes.
`once`	`"per-row"` \| `"per-row-per-window"`	no	`"per-row-per-window"`	`"per-row"`	A cadence trigger with select fires once per row, or once per row in each cadence window (default).

triggers/daily_reminder.json

{
  "on": { "cadence": "daily at 07:00" },
  "select": {
    "type": "ty_3f8v6h2n0c",
    "where": "status == 'draft'",
    "limit": 100
  },
  "run": { "action": "ac_7t9w1y3a5c", "input": { "order": "this" } },
  "once": "per-row"
}

triggers/on_total_change.json

{
  "on": {
    "change": "ty_3f8v6h2n0c",
    "ops": ["update"],
    "props": ["pr_8b2f4h6j0k"],
    "when": "total > old.total"
  },
  "run": { "action": "ac_7t9w1y3a5c", "input": { "order": "this" } }
}

triggers/on_placed.json

{
  "on": { "enter": { "lifecycle": "lc_2k4m6p8r0t", "state": "st_5m7p9r1t3v" } },
  "run": { "action": "ac_7t9w1y3a5c", "input": { "order": "this" } }
}

triggers/on_left_draft.json

{
  "on": { "exit": { "lifecycle": "lc_2k4m6p8r0t", "state": "st_1a3c5e7g9j" } },
  "run": { "action": "ac_7t9w1y3a5c", "input": { "order": "this" } }
}

triggers/on_refused.json

{
  "on": { "fail": "ac_3h5k7n9q1s", "preconditions": ["has_lines"] },
  "run": { "action": "ac_7t9w1y3a5c", "input": { "order": "this" } }
}

TriggerDecl.on

What fires the trigger: a cadence, a change, entering or leaving a state, or a refused call.

One of:

TriggerDecl.on.cadence

On a cadence.

Field	Type	Required	Default	Example	Description
`cadence`	string	yes	—	`"daily at 07:00"`	When it fires, e.g. daily at 07:00, weekly on mon at 09:00, 15m or a 5-field cron; parsed once at compile.

TriggerDecl.on.change

On a change to a row.

Field	Type	Required	Default	Example	Description
`change`	TypeId	yes	—	`"ty_3f8v6h2n0c"`	The type whose rows it watches.
`ops`	(`"create"` \| `"update"` \| `"delete"`)[]	no	—	`["update"]`	The writes that fire it; absent = all three.
`props`	PropId[]	no	—	`["pr_8b2f4h6j0k"]`	An update fires it only when one of these properties changed.
`when`	Expr	no	—	`"total > old.total"`	It fires only when this CX condition holds on the changed row.

TriggerDecl.on.enter

When a row enters a state.

Field	Type	Required	Default	Example	Description
`enter`	StateRef	yes	—	`{"lifecycle":"lc_2k4m6p8r0t","state":"st_5m7p9r1t3v"}`	The state a row enters.

TriggerDecl.on.exit

When a row leaves a state.

Field	Type	Required	Default	Example	Description
`exit`	StateRef	yes	—	`{"lifecycle":"lc_2k4m6p8r0t","state":"st_1a3c5e7g9j"}`	The state a row leaves.

TriggerDecl.on.fail

When a call of an action is refused.

Field	Type	Required	Default	Example	Description
`fail`	ActionId	yes	—	`"ac_3h5k7n9q1s"`	The action whose refused call fires it.
`preconditions`	Ident[]	no	—	`["has_lines"]`	Only a refusal by one of these preconditions fires it; absent = any.

TriggerDecl.select

A cadence trigger runs the action once per selected row.

Field	Type	Required	Default	Example	Description
`type`	TypeId	yes	—	`"ty_3f8v6h2n0c"`	The type whose rows it selects.
`where`	Expr	yes	—	`"status == 'draft'"`	The CX condition a row must hold.
`limit`	integer (between 1 and 1000)	yes	—	`100`	The most rows one firing selects: 1–1,000.

TriggerDecl.run

The call it makes.

Field	Type	Required	Default	Example	Description
`action`	ActionId	yes	—	`"ac_7t9w1y3a5c"`	The action it calls.
`input`	Record<Ident, Expr>	yes	—	`{"order":"this"}`	The CX value of each input of the call.