@frontera-sdk/functions 1.49.0

package/src/types.ts

@@ -0,0 +1,600 @@
+// `import type`, so this is erased at compile time and adds no runtime import —
+// but `@frontera-sdk/blueprint` is still a real `dependencies` entry, because
+// `WhereNode` is part of this package's PUBLIC type surface: anyone consuming
+// `AutomationContext` needs it to resolve. See the packaging note in
+// docs/superpowers/specs/2026-07-29-automations-ctx-blueprint-query-design.md —
+// a subset install that cannot resolve it aborts `bun install` outright.
+import type { WhereNode } from '@frontera-sdk/blueprint/types'
+
+/**
+ * Cron, manual, and agent for now; event and webhook land with Event Triggers.
+ *
+ * The `?: never` members are load-bearing. Without them `{ cron, manual }`
+ * typechecks — TypeScript's excess-property check admits any key present on
+ * *some* member of a union — and the runner would have to decide at runtime
+ * what a both-shaped trigger means.
+ *
+ * `agent` is deliberately NOT part of that exclusion. Cron and manual answer
+ * "what fires this on its own"; `agent: true` answers "may a bound agent call
+ * this", which is an orthogonal question — a nightly reconciliation that an
+ * analyst can also ask an agent to run on demand is one automation, not two.
+ * So `agent` rides alongside either, and the third arm exists for the
+ * agent-only automation, which has no self-starting trigger at all.
+ *
+ * Declaring it is only the AUTHOR's half of the permission. A workspace
+ * operator must still bind the automation to one named agent before any tool
+ * is projected; see the design in
+ * docs/superpowers/specs/2026-08-27-agent-callable-automations-design.md.
+ */
+export type AutomationTrigger =
+  | { cron: string; manual?: never; agent?: true }
+  | { cron?: never; manual: true; agent?: true }
+  | { cron?: never; manual?: never; agent: true }
+
+/**
+ * An author-time affordance, not a validation gate.
+ *
+ * `blueprint:read` is a literal, so the compiler completes it and offers "Did
+ * you mean 'blueprint:read'?" on a typo. `agent:${string}:run` admits any slug
+ * — including one that names no agent — so the union cannot be read as proof
+ * that a grant is well-formed. The runtime gate is `validateManifest` in
+ * `manifest.ts`; this exists to guide the author as they type.
+ *
+ * Widening it later (adding `notify:*`, `governed:*` with Governed Writes) is a
+ * non-breaking change. Narrowing `string` to a union later would break every
+ * automation already written, so it starts narrow.
+ */
+export type Grant =
+  | 'blueprint:read'
+  | `agent:${string}:run`
+  /**
+   * One capability of one Plugin install: `plugin:<install>:<capability>`.
+   *
+   * `<install>` is the install's name as `frontera plugin list` shows it
+   * (lowercase, no spaces); `<capability>` is the capability's name on that
+   * install. One grant per capability — there is no wildcard, for the same
+   * reason `http:` has none: the manifest is the reviewable list of what the
+   * automation can reach.
+   */
+  | `plugin:${string}:${string}`
+  /** One EXACT host, no wildcards. `http:api.stripe.com` matches that host and
+   *  nothing else — a wildcard would ask a reviewer to reason about
+   *  subdomain-takeover risk, and the answer is usually wrong. */
+  | `http:${string}`
+  /** The NAME of a workspace secret. Its VALUE never enters this process: you
+   *  name it, the platform injects it server-side. */
+  | `secret:${string}`
+  /** One EXACT published Action apiName. `governed:approveInvoice` permits
+   *  submitting that Action and nothing else.
+   *
+   *  Not wildcardable, for the same reason `http:` is not: a reviewer reading
+   *  `governed:*` would have to know the whole current Action catalog — and the
+   *  answer changes with every release — to know what the automation may do. */
+  | `governed:${string}`
+
+/** One declared run input. A deliberate subset of JSON Schema — the same
+ *  philosophy as the grant grammar: small enough that a wrong shape is
+ *  refusable with a sentence, wide enough for real parameters. */
+export interface InputFieldSpec {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'file'
+  /** Refused at run start when absent. Mutually exclusive with `default`. */
+  required?: boolean
+  /** Applied at run start when the field is absent. Cron runs rely on these.
+   *  Not permitted on a `file` field — a file has no meaningful literal default. */
+  default?: unknown
+  description?: string
+  /** Allowed values — string and number types only. */
+  enum?: readonly (string | number)[]
+  /** `file` type only. Allowed MIME patterns, e.g. `['image/*', 'application/pdf']`.
+   *  A declaration aid: the value on the run row is only a reference, so this is
+   *  enforced server-side at upload and at run start, never against the value here. */
+  accept?: readonly string[]
+  /** `file` type only. Maximum upload size in bytes, enforced server-side. */
+  maxBytes?: number
+  /**
+   * Mask this field's VALUE wherever a person reads the run.
+   *
+   * What it changes: the run list, the run page and `frontera function runs`
+   * show a placeholder instead of the value. What it does NOT change: the
+   * handler, every resumption and every retried attempt receive the real value,
+   * because the run row still holds it — this is a display control, not
+   * storage encryption and not an access control.
+   *
+   * What it CANNOT cover, stated here so the flag never reads as a promise it
+   * does not keep:
+   *
+   *  - `ctx.log('…', { key: ctx.input.token })` — an author writing a value
+   *    into a step detail publishes it, and nothing here can intercept that.
+   *  - a redacted value the author TRANSFORMS before using it. The agent
+   *    transcript on the run page is masked by exact occurrence, so a value
+   *    interpolated into a prompt — or quoted back in the reply — is replaced.
+   *    A value upper-cased, truncated or reformatted first no longer matches
+   *    and is not found. Exact match is what can be done without guessing at
+   *    substrings; the alternative, withholding transcripts entirely for any
+   *    run with a redacted input, would take the review surface away from
+   *    exactly the runs that most need reviewing.
+   *  - `default` and `enum`, which are published in the version manifest and in
+   *    any tool schema built from it. Declaring either alongside `redact` is
+   *    refused at deploy for exactly that reason.
+   *  - the run's own `result` and error message. A handler that returns the
+   *    value — `return { note: ctx.input.customer_note }` — or throws an error
+   *    quoting it publishes it on the same run page, unmasked, next to the
+   *    masked input it came from. Only the INPUT is masked; what the handler
+   *    chooses to emit is the handler's decision.
+   *  - anything already recorded. Versions are append-only and the mask is
+   *    frozen onto each run when it starts, so adding `redact` masks future
+   *    runs and never rewrites history.
+   *
+   * A credential still belongs in a `secret:` grant, whose value never enters
+   * this process at all. `redact` is for the ordinary personal or commercial
+   * detail a run legitimately takes and a bystander has no reason to read.
+   */
+  redact?: boolean
+}
+
+
+/**
+ * The value of a `file`-typed input.
+ *
+ * A REFERENCE to an already-uploaded file, never its bytes: `fileId` is the
+ * canonical handle from the platform's unified file registry (see
+ * docs/superpowers/plans/2026-08-27-unified-file-layer.md). Bytes live in
+ * storage; only this small id rides on the run row, so the 64KB input cap is
+ * untouched.
+ *
+ * One reference, two entry points: the run-form uploader gets a `fileId` for a
+ * file a person drops in, and an agent passes the `fileId` of a chat attachment
+ * it is already holding — both resolve identically downstream. The client never
+ * supplies a trusted path or URL; the SERVER authorizes the `fileId` against the
+ * caller's workspace (`resolveFile`) and resolves it to bytes/URL when read.
+ */
+export interface FileRef {
+  fileId: string
+}
+
+export type InputsSchema = Record<string, InputFieldSpec>
+
+export interface AutomationManifest {
+  name: string
+  trigger: AutomationTrigger
+  grants?: readonly Grant[]
+  /**
+   * Declared run inputs, validated and defaulted at run start. Absent means
+   * this automation takes no input — starting a run WITH input for such a
+   * version is refused. See `InputFieldSpec`.
+   */
+  inputs?: InputsSchema
+  concurrency?: number
+  /**
+   * Times the platform may retry a run that FAILED. Default 0, and the opt-in
+   * is the contract.
+   *
+   * Setting this asserts your handler is safe to run twice. With `ctx.http` that
+   * is a real claim rather than a formality — a retried run that charged a card
+   * charges it again, and the platform cannot check idempotency on your behalf.
+   * Per-automation, not global, because you are the only one who knows.
+   *
+   * Retries do NOT extend the ctx call budget: each attempt is a separate run
+   * with its own meter.
+   *
+   * With steps, this is a bound on RUN attempts, and a step that fails is what
+   * consumes one. Completed steps are not re-executed on the next attempt —
+   * they return their stored results — so a retry resumes from the failure
+   * rather than starting the work again. That is the point of putting a call
+   * that costs something inside a step: `retries: 2` on a handler whose work is
+   * all in steps re-runs only the step that failed, while the same setting on a
+   * handler with no steps re-runs everything.
+   */
+  retries?: number
+  description?: string
+}
+
+/**
+ * What `automation()` guarantees once defaults are applied — nothing optional
+ * left for a consumer to re-handle. Downstream code takes this, not
+ * `AutomationManifest`, so it never re-derives a fact already established.
+ */
+export interface ResolvedAutomationManifest extends AutomationManifest {
+  // Every member is readonly, not just the two with defaults. `Object.freeze`
+  // in `define.ts` freezes the whole object at runtime, so leaving `name` or
+  // `description` mutable in the type means `d.manifest.name = 'x'` compiles
+  // and then throws — the same compile-clean/throw-at-runtime gap that the
+  // removed `as string[]` cast used to create.
+  readonly name: string
+  readonly trigger: Readonly<AutomationTrigger>
+  readonly grants: readonly Grant[]
+  readonly inputs?: Readonly<InputsSchema>
+  readonly concurrency: number
+  readonly retries: number
+  readonly description?: string
+}
+
+export interface AgentHandle {
+  /**
+   * One headless agent turn. `options.files` hands the agent already-uploaded
+   * files by canonical id — the same `{ fileId }` a `file`-typed run input
+   * carries, so an input forwards directly: `run(p, { files: [ctx.input.doc] })`.
+   * Each id is authorized against this run's workspace and the bytes are staged
+   * onto the agent's computer; the agent is told the staged paths.
+   */
+  run(prompt: string, options?: { files?: readonly FileRef[] }): Promise<{ text: string }>
+}
+
+/**
+ * What `ctx.file(ref)` resolves to: a short-lived signed URL plus the
+ * authoritative mime/size resolved at upload. `null` only in a dry dev run.
+ */
+export interface ResolvedFileHandle {
+  fileId: string
+  signedUrl: string
+  mimeType: string
+  sizeBytes: number
+  name: string | null
+}
+
+/** What `ctx.plugin(install).call(...)` resolves to. */
+export interface PluginCallResult<T = unknown> {
+  /** Whatever the capability returned. Shape is the plugin's, not the platform's. */
+  data: T
+}
+
+export interface PluginHandle {
+  /**
+   * Invoke one capability of this install.
+   *
+   * Governed by the install's policy exactly as an agent's tool call is —
+   * a disabled install, a `read_only` Action policy, a parameter constraint
+   * or a missing workspace account all refuse here with the reason named.
+   * A capability that requires approval cannot be called from an automation
+   * at all (nobody to ask), and `deploy` refuses the grant up front.
+   *
+   * A failure reported by the plugin itself is thrown, carrying the plugin's
+   * message. A success resolves to `{ data }` — there is no `ok` flag to
+   * branch on, only the value.
+   *
+   * Dry in a dev run: returns `{ data: null }` and sends nothing.
+   */
+  call<T = unknown>(
+    capability: string,
+    input?: Record<string, unknown>,
+  ): Promise<PluginCallResult<T>>
+}
+
+/**
+ * Durable steps.
+ *
+ * A step is the unit the platform can memoize, retry and draw. Work inside one
+ * runs at most once per run; work outside one runs again every time the
+ * platform resumes the handler, which it does after every step completes.
+ *
+ * That resumption is the whole model and it is what the three rules below are
+ * about — none of them is a style preference.
+ */
+export interface StepApi {
+  /**
+   * Run `fn` as a durable step and return its result.
+   *
+   * Three rules, all enforced or observable rather than advisory:
+   *
+   * 1. **`name` must be unique within a run.** The platform memoizes by it, so a
+   *    repeated name would silently hand back the FIRST call's result. Inside a
+   *    loop, put the index in the name — `` `submit:${i}` ``. A repeat fails the
+   *    run naming the collision rather than returning the wrong value.
+   * 2. **The result must be JSON-serializable.** It is stored and replayed, so a
+   *    `Date` comes back as a string and a class instance comes back as a plain
+   *    object. Return data, not objects with behaviour. It is also recorded on
+   *    the step's row — capped, and replaced by its size when it is too large —
+   *    so the run trace can show what the step produced. Never return a secret
+   *    from a step: details are rendered verbatim in the Console.
+   * 3. **Code outside a step re-executes.** After each step the handler restarts
+   *    from the top with completed steps returning their stored results. A
+   *    `ctx.http` call sitting outside a step therefore fires once per step, and
+   *    spends its call budget every time. The Console flags such calls on a run
+   *    that used steps.
+   */
+  run<T>(name: string, fn: () => Promise<T>): Promise<T>
+
+  /**
+   * Park the run for `ms` milliseconds, durably, under a unique name.
+   *
+   * On the platform this is a real checkpoint: the run stops occupying a
+   * worker and resumes after the delay — pace provider polls with it (a
+   * measured 429 arrived after ~7 back-to-back polls). In `createTestContext`
+   * and in dev runs it records and returns immediately, so tests and dry runs
+   * never actually wait. Shares the name-uniqueness rule with `run`: the
+   * platform memoizes both by name.
+   */
+  sleep(name: string, ms: number): Promise<void>
+}
+
+/**
+ * The 13 lifecycle states a governed Action Request can hold.
+ *
+ * A deliberate copy of a WIRE contract, not shared code — same reasoning as
+ * `RegistryEntry` in the runner: this package must install from public npm with
+ * a three-package dependency list, and importing the service's own enum would
+ * drag drizzle and the schema into an author's `bun install`. The service's
+ * `ACTION_REQUEST_LIFECYCLE_STATES` is the source of truth; the response proves
+ * the two agree.
+ */
+export type ActionRequestLifecycle =
+  | 'received'
+  | 'awaiting_approval'
+  | 'ready'
+  | 'executing'
+  | 'finalizing'
+  | 'succeeded'
+  | 'rejected'
+  | 'expired'
+  | 'cancelled'
+  | 'failed'
+  | 'outcome_unknown'
+  | 'awaiting_resolution'
+  | 'closed_unknown'
+
+/**
+ * `subjectRef` and `expectedSubjectVersion` are paired deliberately.
+ *
+ * The plane requires BOTH for an Action over an existing subject and refuses
+ * BOTH for a create Action, so independently-optional fields would let an
+ * author write a submission that cannot be accepted and only find out at
+ * runtime. Which arm applies is the Action's decision, not the caller's — read
+ * it off the Action's `subject.mode`.
+ */
+export type ActionSubmission = {
+  /** Published Action apiName. Requires a `governed:<apiName>` grant. */
+  action: string
+  input: Record<string, unknown>
+  /** Required when the Action's definition says so. */
+  reason?: string
+  /**
+   * Tells two submissions from the SAME step apart.
+   *
+   * A step submits once by default. The idempotency key is derived from the run
+   * and the step alone, so a submission re-reached by a resumption or by a
+   * retried attempt is the SAME key and the plane hands back the original
+   * request instead of making a second one. Your own retry loop behaves the
+   * same way: a submission that FAILED is not recorded, so submitting again
+   * after catching a transport error re-sends and the plane replays.
+   *
+   * What you cannot do by default is submit twice on purpose. Two submissions
+   * the platform cannot tell apart derive one key AND one semantic
+   * fingerprint, so the plane would replay the first and answer both calls with
+   * the same id — no error, one effect, a green run. Rather than let that
+   * happen, the second call is refused before it leaves your process, naming
+   * this field.
+   *
+   * Pass a distinct `submissionKey` per submission to say you meant it — a
+   * business identity is the right value, not a counter:
+   *
+   * ```ts
+   * await ctx.step.run('flag', async () => {
+   *   for (const row of rows) {
+   *     await ctx.action.submit({
+   *       action: 'flagForAudit',
+   *       // Stable for THIS row across every attempt. An array index is not:
+   *       // if the re-read returns the rows in another order, an index would
+   *       // bind row B's submission to row A's key.
+   *       submissionKey: row.id,
+   *       input: { rowId: row.id },
+   *     })
+   *   }
+   * })
+   * ```
+   *
+   * It must be stable across attempts for the same intended submission, which
+   * is why the platform cannot derive it for you — only your code knows which
+   * of two submissions is "the same one again". An empty string is refused;
+   * omit it entirely to mean "this step submits once".
+   */
+  submissionKey?: string
+} & (
+  | {
+    subjectRef: { objectTypeId: string; objectId: string }
+    /** The version you believe the subject is at: a submission built from a
+     *  stale read must lose rather than overwrite. */
+    expectedSubjectVersion: string
+  }
+  | { subjectRef?: never; expectedSubjectVersion?: never }
+)
+
+export interface ActionSubmitResult {
+  requestId: string
+  /**
+   * Where the request stopped, NOT whether the effect happened.
+   *
+   * `ready` means accepted and queued for dispatch. `awaiting_approval` means
+   * the Action requires a human and one has not decided yet — a normal return,
+   * not an error. Neither is a completed business fact.
+   */
+  lifecycle: ActionRequestLifecycle
+}
+
+/**
+ * `notify` still arrives with a later slice; `governed` is here.
+ */
+export interface AutomationContext {
+  runId: string
+  workspaceId: string
+  /**
+   * The values this run was started with — validated against the manifest's
+   * `inputs` schema and fixed on the run row at start, so every resumption
+   * and retried attempt sees the same object. `{}` when the manifest declares
+   * no inputs. Visible in the run trace by design: never put a secret here —
+   * `secret:` grants are the credential path.
+   */
+  input: Record<string, unknown>
+  /** Never rejects — telemetry must not be able to fail a run. */
+  log(message: string, data?: Record<string, unknown>): Promise<void>
+  agent(slug: string): AgentHandle
+  /**
+   * Resolve one of THIS run's `file` inputs to a readable form (signed URL +
+   * authoritative mime/size). No grant — it only reads files the run was given;
+   * any other fileId is refused. `null` in a dry dev run.
+   */
+  file(ref: FileRef): Promise<ResolvedFileHandle | null>
+  /** One Plugin install, by the name `frontera plugin list` shows. Needs `plugin:<install>:<capability>` per call. */
+  plugin(install: string): PluginHandle
+  http: {
+    /**
+     * Call an allowlisted host, optionally with a workspace secret injected
+     * server-side.
+     *
+     * Requires an `http:<host>` grant, and an `secret:<name>` grant when `auth`
+     * is used. The secret's VALUE never enters this process — that is deliberate:
+     * a credential this process never held cannot be leaked by a stray
+     * `ctx.log`, an exception serialiser, or a dependency, and step details are
+     * rendered verbatim in the Console.
+     *
+     * An upstream 4xx/5xx comes back as `status`, not as a throw. An API
+     * answering 404 is data; only failures of the mechanism reject.
+     */
+    fetch(req: HttpRequest): Promise<HttpResponse>
+  }
+  blueprint: {
+    query<T = Record<string, unknown>>(
+      objectType: string,
+      options?: BlueprintQueryOptions,
+    ): Promise<BlueprintQueryResult<T>>
+  }
+  /**
+   * Durable steps. See `StepApi`.
+   *
+   * Present on every automation — a handler that uses no steps behaves exactly
+   * as it did before this existed, because a run with no steps is never
+   * resumed.
+   */
+  step: StepApi
+  action: {
+    /**
+     * Ask the governed write plane to perform one named business change.
+     *
+     * This is the ONLY way an automation changes a system of record. Your code
+     * never holds a write handle: you describe the change, and the plane
+     * authorizes it, approves it if the Action says so, dispatches it, confirms
+     * it and records it. An Action that declares `approval: required` cannot be
+     * talked out of it by the caller.
+     *
+     * Two rules:
+     *
+     * 1. **It must be called inside `ctx.step.run`.** Code outside a step
+     *    re-executes after every step boundary, so a submit sitting there would
+     *    fire once per boundary. Inside a step it runs once, and the step —
+     *    identified by the row the service itself issued — is what makes the
+     *    idempotency key stable across resumption and across a retried run.
+     *
+     *    The service checks this rather than taking your word for it: the
+     *    submission carries a step row id, and a submission whose id names no
+     *    open step of this run is refused. What that check cannot do is make a
+     *    determined bundle behave — your code runs unsandboxed in the same
+     *    process as the run token, so it could open a step row purely to submit
+     *    inside it. The bound is that such a step is a real row and shows up in
+     *    the run trace, not that it is impossible.
+     * 2. **It never waits.** It returns as soon as the request is durably
+     *    accepted. A run has nobody to ask for an approval and ten minutes to
+     *    live, so blocking on a human is not something this can offer —
+     *    `awaiting_approval` is a normal return value.
+     *
+     * The returned `lifecycle` is where the request stopped, not proof of
+     * effect. Poll the ledger, or let the Action's Business Event tell you.
+     */
+    submit(request: ActionSubmission): Promise<ActionSubmitResult>
+  }
+}
+
+export interface HttpRequest {
+  url: string
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  headers?: Record<string, string>
+  /** String only — no streaming, no binary. */
+  body?: string
+  /** Inject a workspace secret into one header. Needs a `secret:<name>` grant. */
+  auth?: { header: string; secret: string; prefix?: string }
+}
+
+export interface HttpResponse {
+  status: number
+  headers: Record<string, string>
+  /** Capped at 1 MB. Exceeding the cap is an error, never a truncation — a
+   *  silently shortened response is a wrong answer that looks right. */
+  body: string
+}
+
+export interface BlueprintQueryOptions {
+  /** The real Blueprint filter DSL, not a shorthand — `and`/`or`/`not`, ranges
+   *  and date presets all work. A convenience subset with no escape hatch is the
+   *  thing the first "overdue OR flagged" automation would have to work around. */
+  where?: WhereNode
+  select?: string[]
+  /** `dir`, not `direction` — matches `QueryRequest` exactly. */
+  orderBy?: Array<{ property: string; dir: 'asc' | 'desc' }>
+  /** Default 100, clamped to 1000. Exceeding the cap sets `hasMore`; it never
+   *  truncates silently. */
+  limit?: number
+  /** Opaque. Pass back the previous result's `nextPageToken`; absent means the
+   *  first page. Cursor-based, so a scan stays correct while the table moves
+   *  underneath it — which a cron-driven automation's table always does. */
+  pageToken?: string
+}
+
+export interface BlueprintQueryResult<T = Record<string, unknown>> {
+  rows: T[]
+  /** True when the query matched more rows than were returned. */
+  hasMore: boolean
+  /** Present iff `hasMore`. Feed to the next call's `pageToken`.
+   *
+   *  Forwarded rather than narrowed away on purpose: `hasMore` on its own is a
+   *  fact the author can do nothing about, which is how a digest over the first
+   *  500 of 5,000 rows reports success. */
+  nextPageToken?: string
+}
+
+export type AutomationHandler = (ctx: AutomationContext) => Promise<unknown>
+
+export interface AutomationDescriptor {
+  readonly manifest: ResolvedAutomationManifest
+  readonly handler: AutomationHandler
+}
+
+/**
+ * How a run came to exist, named once so the two sides of the invoke event
+ * cannot drift.
+ *
+ * This is not decoration. The service publishes `source` on the invoke event,
+ * the RUNNER resolves it back and posts it to the open-run call, and the
+ * service then refuses an invocation ticket arriving under a source that does
+ * not expect one. So a source the service knows and the runner does not is not
+ * a mis-filed run — it is no run at all: the ticket rides along, the open-run
+ * call 400s, and the caller waits forever on a request that never became
+ * anything. That is precisely how the App lane shipped broken.
+ *
+ * Both packages depend on this one, so the list lives here rather than being
+ * spelled out in each. Adding a source means adding it here, and the two
+ * consumers pick it up by construction.
+ *
+ * `cron` is deliberately absent: it is what the runner INFERS when the event
+ * names no source at all, so it is never carried on an event.
+ */
+export const EVENT_TRIGGER_SOURCES = ['manual', 'rehearsal', 'agent', 'app'] as const
+export type EventTriggerSource = (typeof EVENT_TRIGGER_SOURCES)[number]
+
+/**
+ * The sources whose runs MUST arrive with an invocation ticket.
+ *
+ * A run under one of these has a caller whose identity exists only on the
+ * ticket, so a missing one is refused rather than opened unattributed. A ticket
+ * under any other source is refused too — it means the event was tampered with
+ * or two payloads got mixed.
+ */
+export const TICKETED_TRIGGER_SOURCES = ['agent', 'app'] as const
+export type TicketedTriggerSource = (typeof TICKETED_TRIGGER_SOURCES)[number]
+
+export function isEventTriggerSource(value: unknown): value is EventTriggerSource {
+  return typeof value === 'string'
+    && (EVENT_TRIGGER_SOURCES as readonly string[]).includes(value)
+}
+
+export function isTicketedTriggerSource(value: unknown): value is TicketedTriggerSource {
+  return typeof value === 'string'
+    && (TICKETED_TRIGGER_SOURCES as readonly string[]).includes(value)
+}