Built-ins
A workflow gets these on ctx by listing them in uses, next to its operations: "approval" (see Approvals), "sleep" and "all". describeConfig lists them as each workflow’s builtins.
Every workflow has ctx.runId, ctx.startedBy and ctx.now(), without uses. ctx.startedBy is who started the run, { id, email?, github?, subject? } (StartedBy): the principal’s id (a person’s, visitor:<login>:<subject>, token:<id>), for a visitor the email and the GitHub login their site’s login verified (the login when they signed in with GitHub or linked it, with the company’s GitHub App’s client), and for an api token the subject its row acts for (SanomaClient.tokens, read at the start, never taken from the caller), so a workflow can tell whose a record is. await ctx.now() is the time in epoch milliseconds, recorded so a replay reads the same. A date is made from it: with const now = await ctx.now(), new Date(now).toISOString() is ISO 8601 text, which a collection’s date field takes (.slice(0, 10) for the day alone), and new Date(now + 86_400_000) is a day later, from the same reading. The lint refuses only the uses of Date that read the clock, Date.now(), new Date() and Date() (and Date passed on, which it cannot follow); new Date(value), Date.parse, Date.UTC and instanceof Date read none (see Keeping workflows replay-safe). Read a date in UTC (toISOString, getUTCHours) and parse ISO 8601 text with an offset: the local-time methods (getHours, toLocaleString) and other text depend on the worker’s time zone, which a replay on another worker may not share.
ctx.sleep({ until }) takes an ISO 8601 date-time with an offset (2026-10-07T09:00:00Z) or epoch milliseconds, and a time already past does not wait; ctx.sleep({ minutes: 5 }) takes a duration from ms, seconds, minutes, hours and days, none negative. A request it can’t read fails the run with invalid_input, as does an operation input its schema refuses. Each sleep writes a sleep.started record before it waits, with until: the time asked for, or for a duration, the record’s at plus the duration, as the runtime saw it.
ctx.all([() => …, () => …]) declares a fan-out: work that could go in any order, such as one post per network. It calls the members one after another, in array order, each awaited before the next starts, and returns their outputs in that order, each typed as its member’s. It adds no concurrency: calls through ctx run one at a time anyway, and ctx.all says what belongs together, so the ledger and a graph of the run can show it. Every record written while a member runs (its operation calls, its approvals, its sleeps) carries group: { id, index, size, node }: id is all:<seq>, the ledger seq the run’s next record would take when ctx.all began (so the same on a replay), index the member’s position, size the member count and node the ctx.all call’s outline node. Records outside a group have no group. The first member that throws stops the group: its error is rethrown as it is, and the members after it never run. A ctx.all inside a member fails with invalid_input (ctx.all cannot be nested), as does one started while another is still running (a ctx.all is already running: await it before the next) and an argument that is not a list of functions; an empty list returns [] and writes nothing.
const [post, broadcast] = await ctx.all([ () => ctx.bluesky.post.create({ text }), () => ctx.resend.broadcast.send({ id: email.id }),]);const comments = await ctx.all(threads.map((id) => () => ctx.forum.comments.list({ id })));The lint refuses Promise.all and Promise.allSettled in workflows, pointing at ctx.all, and Promise.race and Promise.any: calls through ctx run one at a time, so nothing races; pick one call, or sleep and then check.
The runtime’s own operations
Section titled “The runtime’s own operations”What a workflow cannot do itself, the runtime does as operations of the vendor sanoma, in every config with their driver: import { sanoma } from "sanoma", list them in uses and call ctx.sanoma.<group>.<op>. They are decided by the policy (Sanoma::Action::"sanoma.secret.generate"), recorded in the ledger when called in a workflow, and never answer a secret’s value. sanoma.run.inspect also permits direct reads under the same policy; the other operations below require a workflow. Secret generation, token storage and enrollment destinations cannot use the reserved SANOMA_… prefix. secret.delete additionally accepts database URL exports named SANOMA_DATABASE_URL_<EXPORT>; other runtime bootstrap names remain protected. secretStore.prepare may reference a database URL stored under that prefix as its source.
| Operation | Input | Output | What it does |
|---|---|---|---|
sanoma.run.inspect |
{ runId } |
{ runId, status, workflow? } |
Reads run-status metadata in the configured application and database, without inputs, outputs or errors. Effect read |
sanoma.secret.generate |
{ name, kind: "random" | "ssh-rsa" } |
{ name, publicKey? } |
Stores a value under name (upper case) unless one is stored: random, 32 random bytes as a generate marker makes; ssh-rsa, an RSA key pair as going live’s deploy key, its private half (PEM) stored and its public half (ssh-rsa <base64>) answered, from what is stored, so a name stored already answers its own. Effect write |
sanoma.secret.delete |
{ name } |
{} |
Deletes the selected stored value, including a database URL export; none stored is nothing to do. External bindings and read-only stores refuse deletion. Effect write |
sanoma.secretStore.prepare |
{ company, environment, database: { $secret: "NAME" }, store: "RUNTIME_URL" } |
{ company, environment, role, store } |
Initializes an existing company database’s private KMS schema and restricted runtime login; saves its URL under store. Retried with the same stored credential; conflicting ownership is refused. Effect access. See database preparation |
sanoma.invite.mint |
{ host, email, key: secret("NAME") } |
{ url } |
Seals an invite request for email (good for five minutes) under the signing key stored as NAME, an instance’s SANOMA_SIGNING_KEY (sealInvite with that key), posts it to <host>/auth/invite and answers the one-use link it mints; the ledger records url as "<url>". Retried on a status worth retrying. Effect access |
sanoma.token.mint |
{ id?, reference?, subject, groups, store: "NAME" } |
{ id } |
Saves an API token under store before registering its hash and authority. An identical active registration can retry; conflicting or revoked registrations are refused. Answers its id alone; a host takes the value as secret("NAME"). Idempotent. Effect access |
sanoma.token.revoke |
{ id } |
{} |
Revokes the token: it resolves to nobody from now on. Effect access |
sanoma.token.handoff |
{ store: "NAME", challenge } |
{ code } |
Hands off the live api token stored under store, acting for the run’s starter: a one-time code, sch_…, good for five minutes, that POST /api/token/redeem exchanges, with the PKCE verifier of challenge (S256), for the token, once. Its table keeps the code’s hash; the ledger records code as "<code>". Effect access |
sanoma.token.mint accepts either a recorded UUID-shaped id or a stable non-secret reference, never both. Prefer reference when the workflow has no token ID yet: record a value unique to that provisioning incarnation (for example, cloud-signup:<original-run-id>) in the company record before minting. The runtime derives the same ID from that reference across runs. Reuse it with the same secret name, subject and group membership. Explicit IDs also accept the UUID-shaped hash values returned by minting, without requiring RFC version/variant bits. Without either input, the runtime derives an ID from the call’s idempotency key, which is stable for retries of that call but changes in a new run. The bearer is saved in the selected secret store before its hash is registered, so a lost store or database response can reuse the saved value. Only the ID, reference and other non-secret metadata enter workflow inputs, results and the ledger. Do not put credentials in a reference.
An existing registration must have the same ID, bearer, subject and group membership and remain active. A conflict never changes its authority, revives a revoked registration or revokes another token. Keep the saved bearer while its registration outcome is uncertain; deleting the secret does not revoke its token. The provisioning workflow still owns its lifecycle claim and recovery checks: a stable token ID is not a lock and does not reconcile another vendor’s uncertain creation outcome.
For a database URL export, <EXPORT> must contain one or more uppercase letters, digits or underscores: for example, ctx.sanoma.secret.delete({ name: "SANOMA_DATABASE_URL_CLOUD_ACME" }). This removes only that value from the configured store. It does not delete the database, revoke its login or retire a KMS key. The lifecycle workflow must retire the resource and access first, then remove its stored URL; deleting SANOMA_DATABASE_URL or another runtime bootstrap secret remains refused.
sanoma.run.inspect reports active (queued, running or waiting), finished, failed, cancelled, interrupted (recovery attempts exhausted) or missing; an unknown DBOS status remains active. A run outside the configured application is missing. Inspection failures throw a sanitized error rather than reporting completion. The result is a snapshot, not a lock or fence: missing does not prove completion, and cancellation or exhausted recovery attempts do not prove an in-flight vendor action has stopped. Lifecycle recovery must separately establish resource ownership and reconcile uncertain effects before taking over.
A sandbox run calls them over its own secrets and tokens, in memory; invite.mint posts nothing and secretStore.prepare makes no database connections. run.inspect returns missing without querying live runs.
Step names
Section titled “Step names”Every call is a step with a name, which a test and the graph name it by: ctx.github.repository.import(input, { name: "Import the repository" }) and ctx.sleep({ days: 1 }, { name: "Wait a day" }) give one, and an approval is named by its title. Without one, a call is named by its operation’s id (github.repository.import), a sleep Sleep (DEFAULT_SLEEP_NAME, exported from the main entry and sanoma/workflows/shared). A name given, and an approval’s title, is a string literal or a top-level const of the file holding one, so the outline reads it; it is one step’s only (two steps of this workflow are named "Draft"), and a name given may not be what unnamed calls are called, an operation’s id (three dotted words) or Sleep, so a name in a test means one call. Unnamed calls may share their default: one operation in two arms of an if, a retry in a catch, two sleeps. A call in a loop is one step, however often it runs. The outline resolves each call’s name (name on op, sleep and approval nodes: the name given, the title, the operation’s id or Sleep), except a call with a computed segment (ctx[vendor].post.create) and no name, which the operation it calls names in a run, and an approval whose title is no literal, which its title names in a run. The ledger has the name of every step (name on op.called, sleep.started and approval.requested, where a policy hold’s is the held call’s); records written before steps had names have none. StepOptions is the options’ type.
These pages describe sanoma 0.11.24.