` element per bar is the zero-dependency tooltip). ### Forms [Section titled “Forms”](#forms) * Stacked layout. Two columns only when the screen is `lg+` AND fields are short (date pickers, dropdowns). * Label above input, helper text below in `text-xs text-muted-foreground`. Errors replace helper text in `text-rose-500`. * Required fields get a `*` in the label, not a “(required)” suffix. * Submit button anchored to a sticky right-rail summary card on multi-line forms (line items, expense lines) so the user can submit without scrolling. * Inline dynamic field arrays (lines): each row is a single `flex items-end gap-3`, trash button on the right is a ghost icon button. “Add line” is a `variant="ghost"` button with a `Plus` icon, **left-aligned** under the last row. ### Status pills [Section titled “Status pills”](#status-pills) Always a `rounded-full px-2 py-0.5 text-xs font-medium` with a tinted background. These are the light-mode colors (the app is light-mode only): | State | Background | Text | | ------------------------ | ------------------- | ------------------ | | draft / pending | `bg-amber-500/10` | `text-amber-600` | | submitted / in review | `bg-blue-500/10` | `text-blue-600` | | approved / paid / synced | `bg-emerald-500/10` | `text-emerald-600` | | rejected / overdue | `bg-rose-500/10` | `text-rose-600` | | closed / inactive | `bg-zinc-500/10` | `text-zinc-600` | Templates can extend the palette, but the shape and sizing don’t change. ### Empty states [Section titled “Empty states”](#empty-states) Every list, table, and dashboard card has a designed empty state — never a blank box. The pattern is centered lucide icon (24px, `text-muted-foreground`), one line of copy (“No expenses yet — submit your first report”), and an optional primary CTA. Use it on first paint too: an empty dashboard for a new instance should feel intentional, not broken. ### Loading [Section titled “Loading”](#loading) shadcn `` shaped like the eventual content. KPI tile skeletons match the tile height. Table skeletons render 3–5 rows. Never use a generic centered spinner on the page body — only inside button labels and inline indicators. ### Errors [Section titled “Errors”](#errors) * Field-level errors: inline, `text-rose-500 text-xs`. * Mutation errors: sonner toast with a “Retry” action where it makes sense. * Page-load errors: a centered card with the message and a “Reload” button. Never throw a raw stack trace at the user. ### Light mode only [Section titled “Light mode only”](#light-mode-only) Generated apps render in **light mode, always**. No dark default, no `next-themes`, no theme toggle, no `class="dark"` on ``, no `prefers-color-scheme` branch, no theme cookie. Don’t ship the dark palette at all — keep the shadcn neutral light defaults. ## Animations [Section titled “Animations”](#animations) * Card mounts: none. Page transitions: none. * Realtime row flash: a single `bg-emerald-500/10` background for \~1.5s, then `transition-colors` settles. That’s the one visual flourish that earns its keep. * Hover transitions on buttons and links: `transition-colors duration-150`. * Toasts slide in from the top-right corner (sonner default). Position: `top-right`, NOT bottom-center. ## Accessibility floor [Section titled “Accessibility floor”](#accessibility-floor) * Every interactive element has a visible focus ring (shadcn defaults are good — don’t override). * Color is never the only signal: status pills also carry text, deltas also carry `▲` / `▼`. * **Every screen is usable at 390px, 834px and 1280px, with no horizontal scroll at any of them.** Phone, tablet, desktop — check all three before calling a screen done, forms included. A layout verified only at desktop width has not been checked on a phone at all; the three widths are the floor, not three designs. * **Never ship a `hidden md:block` / `md:hidden` layout pair.** Both trees render into the DOM: every input in the “hidden” one stays tabbable, its effects keep running, and two components fight over the same focus and the same ids. Reflow the ONE tree with grid/flex and responsive utilities. If a surface genuinely needs a different structure per breakpoint, it is a different product (see the Konsta carve-out) and it gets its own route, not a display toggle. * Modal / Sheet always has a labeled close button and traps focus. ## What NOT to do [Section titled “What NOT to do”](#what-not-to-do) * No hero gradients, no decorative animated backgrounds. * No emoji in production UI copy. * No “Powered by Claude” / “Built with AI” / similar badges. * No marketing landing page on `/`. The first authenticated route is the dashboard, and the unauthenticated `/` redirects to the instance’s hosted sign-in page (there is no in-app `/login` page). * No `:root { --radius: 1rem; }` style overrides — keep the shadcn neutral defaults so the templates look like the same product. ## Per-template rules go in the prompt [Section titled “Per-template rules go in the prompt”](#per-template-rules-go-in-the-prompt) Things the prompt SHOULD declare (because they vary by template): * Which accent color out of the four. * Status pill states specific to the record (orders have `pending_fulfillment`, expenses have `submitted`, etc.). * KPI tile contents and the time window. * The single hero card the dashboard leads with. * **Whether the app has a phone surface at all**, and which workflow lives on it. This is the door the [Konsta carve-out](#the-one-carve-out-konsta-on-a-phone-surface) comes through: a template whose prompt does not name that surface is shadcn-only, and adding Konsta to it is the same mistake as adding Redux. # Embedding a signing page > Mount a DocuSeal signing page inside your app from a mirrored submitter row — the signing URL is a typed column, the widget is DocuSeal's own, and the failure modes are silent. A customer who has been sent a document to sign should be able to sign it in the app they already have open, rather than in a separate tab. Your instance mirrors every signature request and every party on it, so the signing page is something you mount from an ordinary row read. **There is no Turbobase embed endpoint and no client helper for this.** The signing URL is a column on a table you already read, and the widget is the e-signature provider’s own. That is deliberate: a wrapper would be one more thing between you and a page that already works, and one more thing to go stale when the provider changes it. ## The three tables [Section titled “The three tables”](#the-three-tables) Connecting DocuSeal mirrors three tables into your instance: | Table | One row is | Direction | | ------------------ | ------------------------------------------------------------ | ---------------------------- | | `esign_template` | the reusable document a request is built from | read-only | | `esign_submission` | one signature request | read + create, never an edit | | `esign_submitter` | **one party asked to sign** — this is the one you embed from | read + edit, never a create | They are named for the record CLASS rather than for DocuSeal, so an app written against them keeps working if your instance later mirrors a different e-signature provider. The Direction column is what **your app** may do, which is not the same as what DocuSeal allows. A submission is **create-only** because a request that has gone out cannot be changed — see [Sending a request from your app](#sending-a-request-from-your-app) for what a write that addresses an existing one answers, and what to do instead. A submitter is the mirror image: a party comes into being as part of the request that asks them to sign, so there is no create — but an existing one can be edited, which is how you correct a request that has already gone out. ## Reading the signing URL [Section titled “Reading the signing URL”](#reading-the-signing-url) `esign_submitter.signing_url` is a **typed column**, not a key inside `raw`. That matters: a `raw` key is refreshed only by the periodic poll, while a promoted column is kept current by the webhook leg too. Read it like any other column. ```ts import { turbobase } from '$lib/turbobase'; const { data, error } = await turbobase .from('esign_submitter') .select('external_id, name, email, role, status, signing_url') .eq('submission_external_id', submissionId) .order('role'); ``` Reading these rows needs the `read:esign_submitter` capability, which the built-in **Standard** role carries. A user without it gets an empty array rather than an error — see [Reading the mirror](./reading-data) for why that shape is worth checking for explicitly. A signing URL is a capability Anyone who holds the URL can act as that party. Treat it exactly as you would a password-reset link: never log it, never put it in a query string of your own, and never render one party’s URL on a page another party can see. Render only the URL belonging to the person who is signed in. ## Mounting the widget [Section titled “Mounting the widget”](#mounting-the-widget) Load DocuSeal’s embed script and point it at the URL: ```svelte ``` Nothing about this call goes through your instance. The browser talks to DocuSeal directly; your instance’s only part is having told you the URL. ## What breaks, and what it looks like [Section titled “What breaks, and what it looks like”](#what-breaks-and-what-it-looks-like) Every failure here is quiet — the page renders and the form does not. * **The request is already signed.** `status` is `completed` and the URL loads a read-only receipt rather than a form. Check `status` before mounting and show the completed state yourself; a signed document presented as a form reads as a bug in your app. * **The request has expired.** `esign_submission.expires_at` is in the past. The URL still resolves and the form refuses to submit. Check the parent row. * **The request was archived.** `esign_submission.status` is `archived`. Same shape: the URL resolves and nothing can be done with it. * **`signing_url` is null.** The provider did not return one for this party. `signing_slug` is still set, and the next poll usually repairs the URL — do **not** build a URL from the slug yourself. A hand-built URL that is wrong renders a blank frame with nothing in the console, which is strictly worse than showing nothing. * **The row is stale.** A submitter row is refreshed by the webhook when somebody views, starts, completes or declines. If your instance’s DocuSeal webhook has no shared secret configured, those deliveries are refused and the rows only move on the periodic poll. Your instance’s Health tab for DocuSeal says so in as many words. ## Sending a request from your app [Section titled “Sending a request from your app”](#sending-a-request-from-your-app) Creating an `esign_submission` row sends a real signature request, by email, under your company’s name, to whoever you name. That write is held shut by a per-instance switch that ships **off** — ask your operator to enable it before building against it, and expect the write to be refused with `BIDIRECTIONAL_DISABLED` until they do. Two shapes are worth knowing before you build: * A submission carries `template_external_id` and the parties, and **both are required on a create** — a request with neither a document nor anybody to sign it is refused on the call, before anything is saved or queued. It cannot be **edited** once created: a write that addresses an existing one — by `pgRowId` or by `externalId` — is refused `422 APPEND_ONLY` before anything is written, so your copy never stops matching the document being signed. * **To correct a request that has already gone out, change the party.** A submitter can be edited (`name`, `email`, `phone`, `role`) through `POST /v1/data/esignSubmitter`, addressed by `pgRowId` or `externalId`. It cannot be created on its own — a party comes into being as part of the request that asks them to sign — so a create there is refused `422 EDIT_ONLY`. * **When the document itself is wrong, send a new request.** That is an ordinary create and is unchanged. Archive the old one in DocuSeal. The create goes to the write boundary, `POST /v1/data/esignSubmission`, like every other record write: ```ts await fetch('/v1/data/esignSubmission', { // same-origin, relative path method: 'POST', credentials: 'same-origin', // the turbobase_session cookie rides automatically headers: { 'content-type': 'application/json' }, body: JSON.stringify({ idempotencyKey: crypto.randomUUID(), parent: { template_external_id: '7001', // required — which document to send template_name: 'Mutual NDA', // optional, for your own lists raw: { submitters: [ // the people who have to sign { email: 'first@customer.example', name: 'First Party', role: 'First Party' }, { email: 'second@customer.example', name: 'Second Party', role: 'Second Party' } ] } } }) }); ``` **The signers go under `raw`, not at the top level.** `esign_submission` has no `submitters` column — the parties are rows on `esign_submitter`, which DocuSeal creates for you — so a top-level `submitters` key is refused with `422 UNKNOWN_COLUMN` naming the field. Each party takes `email`, `name`, `phone`, `role` and `source_external_ref` (your own id for them, which comes back on the mirrored submitter row); anything else is dropped. **An incomplete create is refused on the call, not afterwards.** Omit the template or leave the party list empty and you get `422` with `error.code = 'MISSING_REQUIRED_FIELD'` and `error.field` naming `template_external_id` or `raw.submitters`; no row is written and nothing is queued, so there is nothing to clean up. The same two paths are published on `required_inputs` for this record type — read them rather than hard-coding the list, and you cannot be refused for something nobody told you about. You get back `200 { ok, row: { pg_row_id, external_id } }` with `external_id` **null** — DocuSeal mints the request’s id, and your instance sends it in the background. Watch the row you were handed: `write_status` moves `pending` → `synced` and `external_id` fills in when the request has gone out, and the per-party `signing_url` values appear on `esign_submitter` shortly after. Any `write_status` other than `pending` or `synced` means the request has not gone out, and the three say different things about what happens next: * **`needs_input`** — yes. The refusal is released by the record itself, so the `record_write_state` row’s `message` always says what to change. Its `fields` array names the column **when DocuSeal named one**, and is empty when it did not — so render your correct-and-save prompt from the `message` and treat `fields` as the extra that focuses it, never as the test for whether to show it. A `template_external_id` your DocuSeal account no longer has names the column, and carries the id you sent in `requested`; a request DocuSeal turned down over its own content — a party it will not accept, a value its rules forbid — names no column and carries DocuSeal’s own reason in the `message` instead. `requested` is optional either way: it is absent when the column was simply left empty. * **`blocked`** — no. Either the refusal is not released by anything on the record — a credential DocuSeal rejected, a permission the connected account lacks — or DocuSeal could not be reached at all. The `message` is the generic hold and `fields` is empty. Show it and stop; your team is already notified. * **`awaiting_approval`** — nothing is wrong, and nobody has to do anything on this screen. A signature request leaves the company’s account and cannot be unsent, so an instance can be configured to hold one for an operator to approve before it goes. The request is held, not refused: once it is approved the row carries on to `synced` by itself, and the person who saved it needs no second save. Render it as waiting rather than as a failure, and do not offer a correct-and-save prompt — there is nothing on the row to correct. If nobody answers inside the window the row ends `blocked` with `reason_code` saying the hold expired, and sending it again is a fresh request. Sending the request needs the `write:esign_submission` capability, which is **not** in the built-in **Standard** role: a signature request leaves your company’s account under your name and cannot be unsent, so an admin grants it per user. Reading these rows needs only `read:esign_submission`, which every standard user has. # Reading the mirror > How to read the mirrored data efficiently — embeds across linked records, keyset pagination, and the query shapes that silently return nothing. Your instance’s tables are a **mirror** of the source system, not a copy of its UI. Most of the surprises below share one shape: the query succeeds, the page renders, and the data is absent or subtly wrong. Nothing errors. This page is the list of things worth checking before you trust a result. ## Reading rows always runs as a person [Section titled “Reading rows always runs as a person”](#reading-rows-always-runs-as-a-person) **Rows are never read by PostgREST under a token.** A personal access token reaches *schema* that way — `/v1/catalog`, types generation, the authoring MCP — but PostgREST rejects it outright, because a PAT is an opaque bearer rather than a JWT: ```json {"code":"PGRST301","message":"JWSError (CompactDecodeError Invalid number of parts: Expected 3 parts; got 1)"} ``` Until 1.3.x a PAT carrying a `data:read` scope could be traded for a session at `POST /auth/pat-exchange`. Both are gone and neither is coming back. The session it returned was the token owner’s *ordinary* session — write included, for an admin owner — so a long-lived token in a project file was standing write access to production data. Four ways to read rows, each running under a real person’s identity and RLS: **Inside a hosted app**, you need nothing: the app is served same-origin and rides the visitor’s session cookie. `select()` through `src/lib/turbobase.ts` and the signed-in user’s row policies apply. **From a native app you build** — iOS, Android or desktop — sign the person in through the instance’s own OAuth server and read `/rest/v1` with the token it returns. That token *is* their session, so the same row policies fire as in a hosted app; it lasts eight hours and renews quietly, for thirty days from the sign-in, while their approval stands. On day thirty-one the person signs in again. See [building a native app](/tenant/auth-levels/#building-a-native-app). **From your own editor**, connect the [data MCP](/tenant/mcp-server/) as yourself. You sign in once over OAuth and your client gets `list_records`, `get_record` and `search_fields` as tools — scoped to *you*, expiring with your session. Connect it from **Integrations** settings, and revoke it from the *Connected apps* tab of your account settings. **From a script or an unattended agent that is not an AI client** — a label printer, a warehouse script, an overnight integration — present a PAT carrying the [`rest:read` permission](/tenant/access-tokens/) as a bearer at `POST /v1/batch`. You send PostgREST query strings and get their rows back, so your script keeps the read grammar it would use at `/rest/v1`, and the request runs as the administrator who minted the token, under that person’s row-level permissions. `rest:write` beside it reaches `POST /v1/data/`, the upload route and `DELETE /v1/data/` — the same write boundary an app goes through, so your hooks, guardrails and `expectedSyncVersion` all apply. `/rest/v1` itself takes a browser session only and does not accept a token, which is why a script reads through the batch endpoint. **From an AI client without a person signed in**, present a PAT carrying the [`mcp:data` permission](/tenant/access-tokens/) as a bearer at the same data MCP endpoint. Reads run as the administrator who minted the token, under that person’s row-level permissions, and the session behind them is minted inside each request and never handed to your client. Neither credential is granted by default — an administrator ticks it deliberately in the mint dialog — and each read permission is refused the matching write on its own. A token carrying `mcp:data` **alone** cannot change anything, whatever the instance’s MCP write setting says; changing data through that endpoint takes `mcp:write` as well, *and* the instance’s MCP write setting on. Neither pair implies the other, so a token connected to the data MCP is not thereby allowed on the web interface. From an app itself, writes still go through `POST /v1/data` as a signed-in person. ## `permission denied` usually means “not signed in” [Section titled “permission denied usually means “not signed in””](#permission-denied-usually-means-not-signed-in) ```json {"code":"42501","message":"permission denied for table cr_acme_incoming"} ``` This reads as *your role cannot see this table*. Far more often it means **there was no session at all**: PostgREST fell back to the anonymous role, which is denied everything. Check the session before you go looking at grants. In local development this is almost always a dev-proxy gap — the sign-in page loads its assets from `/_app`, so if that path isn’t proxied the login form renders but never hydrates, and you stay signed out with no error. The scaffolded `vite.config.ts` proxies it; don’t remove that entry. ## Five shapes that return nothing [Section titled “Five shapes that return nothing”](#five-shapes-that-return-nothing) ### 1. A `jsonb` custom field is a bare id [Section titled “1. A jsonb custom field is a bare id”](#1-a-jsonb-custom-field-is-a-bare-id) Every mirrored custom field is reported as `jsonb`, which says nothing about what is inside. It is **the bare source internal id**: ```json "cf_ns_custrecord_vendor": 1074 ``` Not `{"value": 1074, "text": "FedEx"}`. There is no display text and — unlike standard columns such as `entity_id` / `entity_name` — **no display twin**. Resolve the id against its lookup table yourself. An app built on the wrapper assumption renders empty cells, which look exactly like an empty table. An empty custom field holds the JSON literal `null`, **not** SQL `NULL`. So `is.null` matches zero rows on these columns, and `lt.0` matches blanks as well as negatives (jsonb sorts `null` below every number). ### 2. The obvious lookup table may be the wrong one [Section titled “2. The obvious lookup table may be the wrong one”](#2-the-obvious-lookup-table-may-be-the-wrong-one) A List/Record field named after a custom record does not necessarily point at it — a carrier field can point at `entity` (vendors) while a `customrecord_acme_carrier` table also exists and holds something else entirely. Confirm the target by checking that real ids resolve to sensible rows, not by matching names. ### 3. Some tables mix kinds in one id space [Section titled “3. Some tables mix kinds in one id space”](#3-some-tables-mix-kinds-in-one-id-space) `entity` holds customers **and** vendors — the same id is a valid row of each. `order` holds every connector’s orders. `GET /v1/catalog/records` marks these with a `sharedTable` note naming the discriminator. Apply it: ```plaintext /rest/v1/entity?entity_type=eq.vendor&external_id=eq.1604 /rest/v1/order?source_system=eq.netsuite ``` Skip it and you will label a vendor with a customer’s name, and both queries will have succeeded. The note only names filters that genuinely narrow, so read it rather than assuming one exists. `discriminators` is empty where nothing separates the kinds at all — `tax_code` holds NetSuite’s `salesTaxItem` and `taxGroup`, so filtering by source excludes nothing — and there the `hint` tells you to match on `pg_row_id` and check the row you read. Where a filter narrows only partly, the hint names the record types it leaves behind. ### 4. Five timestamps are the mirror’s, and two of them are worth rendering [Section titled “4. Five timestamps are the mirror’s, and two of them are worth rendering”](#4-five-timestamps-are-the-mirrors-and-two-of-them-are-worth-rendering) `created_at`, `updated_at`, `synced_at`, `last_modified_pg` and `source_confirmed_at` are all on **Turbobase’s own clock**, not the source’s, and the catalog marks all five `provenance: "mirror"`. After a bulk sync `created_at`, `synced_at` and `last_modified_pg` are identical across the whole table, so ordering by one of those gives you sync batch order, not business order. `updated_at` is when the row last **changed** — stamped whenever a change arrives from the connected source or one of your own writes edits the record. It is the column to order a “recently touched” list by, and the one `updated_since` filters on. Nothing else moves it: a write-back completing, a freshness confirm, a source-id backfill and a platform maintenance backfill all leave it alone, so a sweep that re-reads a record and finds it unchanged does not make it look edited. Use `created_at` when you want import order — that is the one `updated_at` used to answer by accident. `source_confirmed_at` is the other one worth putting on a screen: it is when the source was last asked about **this row** and agreed with it, whether or not a value moved, so it answers “is this figure current” in the same request that returns the row. It is not `updated_at` — a row re-read thirty seconds ago and found identical has a four-hour-old `updated_at` and a thirty-second-old `source_confirmed_at`. `NULL` means never confirmed, not just-confirmed, so render it as “not confirmed yet” rather than as age zero. For real business dates use `source_modified` (`provenance: "source"`) or the source’s own date field inside `raw`. ### 5. A column can exist and be empty on every row [Section titled “5. A column can exist and be empty on every row”](#5-a-column-can-exist-and-be-empty-on-every-row) `currency_name` and `subsidiary_name` are frequently NULL while `currency_id` / `subsidiary_id` carry the data. A display contract that points at an unpopulated column renders every total unlabelled — worse than wrong when not everything is in one currency. **Check one real row before rendering a column**, not just the schema. ## Follow links with embeds, not a second read [Section titled “Follow links with embeds, not a second read”](#follow-links-with-embeds-not-a-second-read) One request can pull related rows in alongside the row they hang off. Two kinds of link are embeddable, and the first is worth far more than the second: 1. **A header and its lines.** A real foreign key. Works on every instance today, needs nothing declared, and is where nearly all the wasted bytes are. 2. **A `jsonb` custom-field link your instance has declared.** Resolved on the server over `raw->>''`. ### Read a transaction’s lines as an embed — never out of the header’s `raw` [Section titled “Read a transaction’s lines as an embed — never out of the header’s raw”](#read-a-transactions-lines-as-an-embed--never-out-of-the-headers-raw) Every line table carries a real foreign key to its header (`item_receipt_line.parent_pg_row_id` → `item_receipt.pg_row_id`), so PostgREST embeds the lines directly. Name the columns you actually render: ```plaintext /rest/v1/order?select=external_id,tran_date,order_line(line_index,line_order,item_id,quantity) ``` **Order the lines on `line_order`, not on `line_index`.** `line_index` is the line’s identity — the key that does not move when the document is re-read — and it is what you match on when you join one document’s lines to another’s. Treat it as opaque, and never as a position. For a source whose lines are separate records (Salesforce, HubSpot) it is a hash of the line’s own id and carries no order at all; for NetSuite it is the line’s own line id, which is not in display order either — a sales order whose lines are shown 1st, 2nd, 3rd can carry ids 8, 4 and 9. Sorting on `line_index` scrambles the document in both cases. `line_order` is the position a person sees, counting from 1, and twenty line tables carry it. It can be **null** — on a NetSuite line whose position could not be read from the document it was synced with, until that document next changes in NetSuite, and on a source that states no order of its own — so the portable form falls back: `order=line_order.asc.nullslast,line_index.asc`. Six of the fifteen header/line pairs need a **constraint hint** — the `!…` in the next example — because two foreign keys join them. The table below marks which; read that before you copy a line from here. ```plaintext /rest/v1/item_receipt?select=external_id,tran_date,item_receipt_line!item_receipt_line_parent_pg_row_id_fkey(line_number,item_id,quantity) ``` The shape this replaces is pulling lines out of the header’s `raw` — `select=raw` (or `select=lines:raw->item->items`) and then walking the array in the browser. **That is the most expensive query shape on the platform.** A header’s `raw` is the entire source document, line array included; we have measured single requests of that shape at **\~10 MB** on live instances, and a first paint doing it for three record types moves tens of megabytes and takes seconds. The embed above moves kilobytes, because no `raw` column crosses the wire at all. Header / line pairs that embed this way. **Nine embed bare; six need the hint** — copy the exact embed text from the right-hand column: | Header | Line embed | | ----------------------------- | -------------------------------------------------------------------------------------------- | | `order` | `order_line(…)` | | `order_fulfillment` | `order_fulfillment_line(…)` | | `invoice` | `invoice_line(…)` | | `cash_sale` | `cash_sale_line(…)` | | `estimate` | `estimate_line(…)` | | `opportunity` | `opportunity_line(…)` | | `credit_memo` | `credit_memo_line(…)` | | `purchase_order` | `purchase_order_line(…)` | | `vendor_bill` | `vendor_bill_line(…)` | | `item_receipt` | `item_receipt_line!item_receipt_line_parent_pg_row_id_fkey(…)` | | `return_authorization` | `return_authorization_line!return_authorization_line_parent_pg_row_id_fkey(…)` | | `vendor_return_authorization` | `vendor_return_authorization_line!vendor_return_authorization_line_parent_pg_row_id_fkey(…)` | | `journal_entry` | `journal_entry_line!journal_entry_line_parent_pg_row_id_fkey(…)` | | `check` | `check_line!check_line_parent_pg_row_id_fkey(…)` | | `transfer_order` | `transfer_order_line!transfer_order_line_parent_pg_row_id_fkey(…)` | The hint is always the line table’s own name plus `!_parent_pg_row_id_fkey`, so you can derive it rather than memorise the six. #### Why the hint, and what happens without it [Section titled “Why the hint, and what happens without it”](#why-the-hint-and-what-happens-without-it) Those six line tables carry **two** foreign keys to their header — the `parent_pg_row_id` one above, and an older one on the source id (`tran_external_id` / `tran_internal_id` / `je_internal_id`). PostgREST refuses to guess which to traverse and answers **`300` with `PGRST201`**, listing both candidates. The response is helpful, but it is an error: no rows come back. Caution Nothing rescues this at runtime. The client’s fallback for a declared relationship keys on `400`/`PGRST200`; a `300` is neither, so an unhinted embed on these six is a hard error in your app, not a slower-but-correct read. Get the embed text right at author time. **Hint the `parent_pg_row_id` constraint, not the source-id one.** Both resolve the ambiguity, but `parent_pg_row_id` is `NOT NULL` on every line while the source-id column is nullable — a record created in Turbobase and not yet synced to the source has no source id yet, so hinting the older constraint silently drops its lines. That failure looks like “the header has no lines”, which is far harder to spot than a `300`. You can filter, order and cap the embedded rows without touching the parent query, by prefixing the parameter with the embed name (one line, wrapped here for readability): ```plaintext /rest/v1/purchase_order ?select=external_id,purchase_order_line(line_index,line_order,item_id,quantity) &purchase_order_line.quantity=gt.0 &purchase_order_line.order=line_order.asc.nullslast,line_index.asc &purchase_order_line.limit=200 ``` Those parameters filter the *lines*, not the purchase orders — a PO with no matching lines still comes back, with an empty array. Selecting parents *by* what their lines contain is a different problem an embed can’t solve; ask for a view. If your app reads a `*_line` table separately and joins it back to the header on `tran_external_id` in memory, or reads lines out of `raw`, replace it with the embed. Nothing has to be declared and nothing has to be enabled. ### Embedding across a declared `jsonb` link [Section titled “Embedding across a declared jsonb link”](#embedding-across-a-declared-jsonb-link) Some records point at another *record* through a `jsonb` custom field — an item receipt carries the internal id of the purchase order it was created from in `raw->>'createdFrom'`. Where your instance has **declared** that link, embed it: ```plaintext /rest/v1/item_receipt?select=*,created_from_po(*) ``` `created_from_po(*)` pulls each receipt’s originating purchase order into the same response. It is: * **one round trip** — no second read of `purchase_order`, no in-memory join; * **resolved on the server** — the join runs in Postgres over `raw->>'createdFrom'`, not in the browser; * **RLS-scoped** — the embed is filtered by the same row policy as the base read, so it can never surface a row your session couldn’t already see on its own. The links declared on the item-receipt / purchase-order pair: | From | Embed | Pulls in | | ------------------- | ----------------------------- | ------------------------------------------------ | | `item_receipt` | `select=*,created_from_po(*)` | the purchase order the receipt was created from | | `item_receipt_line` | `select=*,source_po(*)` | the purchase order a receipt line traces back to | | `purchase_order` | `select=*,receipt_lines(*)` | the receipt lines booked against the PO | ### Relationships are declared, not discovered [Section titled “Relationships are declared, not discovered”](#relationships-are-declared-not-discovered) Your instance does **not** grow a resolver for every link field it can see. A source account has hundreds of them and a given app uses a handful, so a relationship exists because something asked for it: your app declares the ones it embeds in `public/turbobase.json`, or someone creates one in the instance UI. Declaring is what causes it to be materialized — discovery on its own does nothing. ```json { "name": "ops", "relationships": [ { "name": "inbound_shipment", "sourceTable": "item_receipt", "sourceJsonbKey": "custbody_acme_inbound_shipment", "targetTable": "cr_inbound_shipment" } ] } ``` The list your app can rely on is the list in your own manifest — plus the header→line embeds above, which are structural and always present. **A declared embed works from the moment you declare it.** Materializing the fast path (the resolver function and its index) is a background pass, but you never wait on it and never gate a screen on it: `select()` and `selectPage()` try the native embed first, and while it isn’t armed yet the instance resolves the same embed for you server-side and returns the same rows. Arming changes how fast the read answers, not what it answers — and your code is identical either way, because the fallback reuses the query string you already wrote. One constraint holds only during that window: the instance-resolved path reproduces a straight `rel(columns)` embed exactly, and refuses what it can’t reproduce — nested embeds, `!inner`, spread embeds, embed-scoped filters — with a `501` naming the alias instead of quietly returning different rows. Keep a newly declared embed simple and add nested embeds or `!inner` once it’s armed. (Header→line embeds are never affected; they’re native from the start.) **Spread embeds (`...rel(col)`) are the exception — don’t use them at all.** They aren’t merely unsupported while unarmed: on PostgREST 12 they’re rejected outright, and on 14 the request succeeds but the spread column comes back under its own name alongside the parent’s column of the same name, so the parent’s value is the one you lose. That’s a silent wrong-value bug, so it’s the one shape to avoid armed or not. Select the embedded column normally and read it from the array. ### A declared relationship’s embed is always an array [Section titled “A declared relationship’s embed is always an array”](#a-declared-relationships-embed-is-always-an-array) Even when the link is to-one. `created_from_po` comes back as a one-element array, not an object — `row.created_from_po[0]?.tran_id`, never `row.created_from_po.tran_id`. The second form is `undefined` on every row and renders as an empty column rather than an error, so it survives review easily. This differs from a plain foreign-key embed, where PostgREST follows the cardinality of the FK: a header’s lines come back as an array (`row.item_receipt_line`), but a to-one FK embed like `currency:currency_id(symbol)` comes back as an object or `null`. Declared relationships are uniform because they resolve through a set-returning function, so index into them and you’re right in both directions. ### A missing embed means “not synced yet”, not “no link” [Section titled “A missing embed means “not synced yet”, not “no link””](#a-missing-embed-means-not-synced-yet-not-no-link) Embeds over a `jsonb` link are **eventually consistent**. The resolver matches the link id (`raw->>'createdFrom'`) against the target’s `external_id`. If the target row hasn’t synced yet — a receipt landed before its purchase order — the embed comes back empty (`created_from_po: []`) even though the link id is present on the row. That is a timing gap, **not** a signal that the relationship doesn’t exist. To tell the two apart, read the raw link id itself (`select=external_id,createdFrom:raw->>createdFrom`): if it’s populated but the embed is empty, the target simply hasn’t landed yet and the embed will fill in on its next sync. Don’t render an empty embed as “orphaned”, and don’t write a migration/repair on the strength of one. Header→line embeds don’t have this failure mode — a header and its lines are written by the same sync, so the FK is never dangling. ### A custom record’s children are not lines [Section titled “A custom record’s children are not lines”](#a-custom-records-children-are-not-lines) The third kind of parent/child, and the one that looks most like the first while behaving like the second. In Oracle NetSuite, a **native transaction** owns a real sublist: its lines have no identity of their own, they arrive in the same save as the header, and they get the real foreign key that the whole first half of this section relies on. A **custom record** has no sublist. What you see rendered as one on its form is a **second custom record type** whose rows each carry a List/Record field pointing back at the parent. Each child is a first-class record with its own internal id, its own permissions, and its own place in the mirror. NetSuite draws them under the parent as a convenience; nothing else about them is line-like. So in your instance they are two independent tables with **no foreign key between them**. The link is the promoted column that the parent field was projected into, holding the parent’s `external_id`: ```plaintext turbobase.cr_acme_inbound_shipment -- parent external_id = '162' turbobase.cr_acme_inbound_shipment_item -- child cf_ns_custrecord_acme_isi_parent = '162' ← the link ``` Three consequences: * **There is no `parent_pg_row_id`.** Reaching for it is the single most common mistake here; that column belongs to native `

` (suggested\_kb\_edit\|kb\_correction), `--limit `, `--dry-run`, `--diff` / `--no-diff`, `--no-group`, `--yes` | | `skills push` | Write the hard rules in your standing markdown — the `## Agent rules` findings — as draft agent skills, **grouped by their `###` sub-heading** (the rules under one heading become one skill, named after it; `--no-group` writes one skill per rule). Re-reads your pushed markdown first, like `kb push`. `--reapply` also re-emits rules already applied, which is how a CORRECTED `###` grouping reaches the instance: re-filing a rule under a new heading is the same finding by identity, so it queues nothing on its own. The standing-rule twin of `kb push`: that writes what an agent can look up, this writes what every agent is told on every turn. Prints the plan and asks first. Rules land DRAFT — pushing is not publishing; admin only, on `extensions:deploy`. | `--base-url `, `--app `, `--limit `, `--dry-run`, `--diff` / `--no-diff`, `--no-group`, `--reapply`, `--yes` | | `skills list` | What agent skills exist and which are ACTUALLY injected — `draft`, `unreleased`, `live`. Worth reading before writing another rule. Needs `skills:publish`; admin only. | `--base-url `, `--status ` | | `skills publish` | Publish skills — **live by the time it returns**. Sets visibility and cuts a release scoped to these skills, so publishing one rule cannot ship a colleague’s half-reviewed one. Same one-step shape as publishing a knowledge-base page. Needs `skills:publish`; admin only. | ``, `--base-url `, `--yes` | | `skills unpublish` | The inverse of `publish` — retracts from every prompt immediately and keeps the text, its history and its author. The reversible counterpart to `delete`; prefer it when a rule is merely wrong for now. Needs `skills:publish`; admin only. | ``, `--base-url `, `--yes` | | `skills releases` | Publish/unpublish history, newest first — the rollback targets. Needs `skills:publish`; admin only. | `--base-url ` | | `skills rollback` | Re-point the current skill release at an earlier one. Restores CONTENT only: a skill an operator has since unpublished stays off. Needs `skills:publish`; admin only. | ``, `--base-url `, `--yes` | | `skills delete` | Delete a skill. Permanent, and it stops being injected immediately — no release needed. Prior releases keep their own copy of the text, so a rollback still works. Needs `skills:publish`; admin only. | ``, `--base-url `, `--yes` | | `kb list` | What knowledge-base pages exist and which are ACTUALLY readable — `draft`, `unreleased`, `live`. A page flipped to published but never released reaches nobody, and `visibility` alone does not tell you that. Needs `docs:publish`; admin only. | `--base-url `, `--status ` | | `kb publish` | Publish pages — **readable by the time it returns**. Sets visibility and cuts a release scoped to these pages, so publishing one cannot ship a colleague’s half-written one. Needs `docs:publish`; admin only. | ``, `--base-url `, `--yes` | | `kb unpublish` | The inverse of `publish` — drops the pages out of the reader snapshot immediately and keeps the text and its history. Needs `docs:publish`; admin only. | ``, `--base-url `, `--yes` | | `kb versions` | Knowledge-base release history, newest first — the rollback targets, with the current one marked. Needs `docs:publish`; admin only. | `--base-url ` | | `kb rollback` | Re-point the current knowledge-base release at an earlier one. Needs `docs:publish`; admin only. | ``, `--base-url `, `--yes` | | `kb delete` | Delete a page and its subtree, and stop serving it in the same call. SOFT — restorable from the knowledge-base trash, unlike `skills delete`. Needs `docs:publish`; admin only. | ``, `--base-url `, `--yes` | | `release deploy` | Enqueue a server-side release deploy. UPLOADS the SDF project’s `src/` from your checkout when present; otherwise a solution-only live-fetch deploy. `--target approved` requires `--approved-by`. | `--target ` (required, auto\|approved), `--solution `, `--project `, `--git-repo `, `--git-ref `, `--ref `, `--pr-url `, `--approved-by `, `--base-url `, `--follow`, `--interval-ms ` | | `release status` | Poll a release’s current deploy job. | ``, `--base-url `, `--follow`, `--interval-ms ` | | `release rollback` | Roll back a live release (LIFO-guarded; server-side reverse deploy). | ``, `--base-url ` | | `release list` | List releases, newest-first, with delivered titles + latest status. | `--base-url ` | | `release pull` | Write the project a **failed** release built into a directory: `owned/` (your solutions authored these — edit them) and `context/` (the rest of the bundle — leave alone). Includes the failure log. Read-only. | ``, `--dir ` (required), `--base-url ` | | `release push` | Ship the edited project as a **new** release delivering the same solution. Refuses if a `context/` file changed. `--target approved` requires `--approved-by`. | ``, `--dir ` (required), `--target ` (auto\|approved), `--approved-by `, `--base-url ` | | `sandbox create` | Stand up a fresh local sandbox seeded with a sampled+redacted slice of an instance. | `--from ` (required), `--ttl `, `--sample `, `--base-url ` | | `sandbox destroy` | Drop a sandbox database and remove it from the registry. | `` | | `sandbox list` | List active sandboxes with TTL/expiry; reaps any past their TTL. | *(none)* | | `processes list` | Every process deployed on the instance with its trigger (`manual`, or `scheduled` with the cron AND the timezone), whether it is switched on, and its last five runs. | `--base-url `, `--json` | | `processes runs` | One process’s whole run history, newest first — the read behind “when did this stop working”. | ``, `--base-url `, `--json` | | `processes run` | One run and its step ledger: each step’s disposition, what it wrote, and why it refused. | ``, `--base-url `, `--json` | | `processes invoke` | Start a run of a deployed process. The input is a JSON object, passed whole as the process input. Queued by default (prints the run id); `--sync` waits, bounded by the instance’s budget, and prints the outcome and each step. Needs an `extensions:deploy` token owned by an administrator. | ``, `--input `, `--input-file `, `--sync`, `--base-url `, `--json` | | `processes cancel` | Stop one run. A queued run never executes; a running one stops at its next step boundary and keeps what it already wrote. | ``, `--base-url ` | | `data settle` | Link a row to the record the connected system already created, after a `write_settle_conflict` (`POST /v1/data//settle`). The id comes from the row’s own write state, never from you; a row not in that state answers `409 NOT_SETTLE_CONFLICT`. | ``, ``, `--base-url `, `--json` | | `processes rollback` | Undo a finished run: delete, newest first, only the records its ledger shows it created — never one it updated. Source deletes are paced, so the run reads its progress until they are all sent. | ``, `--base-url ` | | `processes resume` | Carry on a run that stopped waiting on the connected system: the same run picks up at the step it stopped on, so nothing it already wrote is written again. Only a run that ended `committed` with work outstanding; anything else answers `409` naming the state, and a per-source-row process is invoked again instead. | ``, `--base-url ` | | `logs` | Read the platform event log — guardrails, hooks, scheduled tasks, conduits and sync in one stream. `--extension` / `--conduit` / `--process-run` absorb the old `ext logs` and follow a process run. | `--base-url `, `--subsystem `, `--severity `, `--code `, `--since `, `--correlation-id `, `--extension `, `--conduit `, `--process-run `, `--follow`, `--interval-ms `, `--limit `, `--json` | | `mcp` | Run the local stdio authoring MCP server, for clients pointed at a process rather than a URL. | `--base-url ` | *** ## When a command fails [Section titled “When a command fails”](#when-a-command-fails) Every command reports a failure as one line carrying what the instance said, and exits non-zero. Two of those lines are worth recognising on sight: * **`this instance is temporarily unavailable — it is upgrading or restarting. Retry shortly.`** Your instance is not answering — it is being upgraded, it is restarting, or it has been paused. Nothing is wrong with what you ran and nothing was written; retrying in a minute is the whole fix. Every command says it the same way, so a script can match on it. * **`the request did not reach the instance — a proxy or edge answered with an HTML page, so the server gave no detail.`** Something between you and your instance answered instead of it. Check the `--base-url` you passed and any proxy on the way out. **A refusal your instance wrote arrives whole.** When the instance refuses something — a deploy that would leave a recurring job running a process you removed, a module that does not compile — the reason is its own sentence, and the command prints the whole of it, so the half that says what to do about it is never cut off. Only a runaway reason stops short, at 2,000 characters: a build error can carry a compiler’s entire output, and `TURBOBASE_DEBUG=1` below prints even that in full. A body that did NOT come from your instance is still shortened to one line, which is where a proxy’s error page would otherwise land. Set **`TURBOBASE_DEBUG=1`** to put the full form back on any failure: the method, the path, the status, and the server’s response body untruncated — the form worth pasting into a bug report. `0`, `false` and empty are off. ```sh TURBOBASE_DEBUG=1 turbobase kb push --dry-run ``` ## `auth` — sign in, and pick which instance you are talking to [Section titled “auth — sign in, and pick which instance you are talking to”](#auth--sign-in-and-pick-which-instance-you-are-talking-to) Credentials live in `~/.turbobase/credentials`, keyed by base URL. One of them is the **active** instance: the default every other command uses when you omit `--base-url`. ### `auth login` [Section titled “auth login”](#auth-login) ```sh turbobase auth login --base-url https://acme.turbobase.app --token tb_pat_xxxx turbobase auth login --base-url https://acme.turbobase.app --token "$TURBOBASE_PAT" # CI ``` `--token` is required — there is no browser sign-in leg, so the same invocation works on a laptop, a headless box, and a CI runner. Stores the PAT keyed by base URL, makes that instance the active default, and prints `signed in to — now the active instance` (with a count of any other stored credentials). After storing the token the CLI probes the instance — it checks that the URL actually serves the `/v1` API and that the token authenticates — and warns loudly on a wrong host or a rejected token instead of silently claiming success; `--no-verify` skips the probe. See the [overview](/cli/overview/#authenticate--turbobase-auth-login) for the full sign-in model. ## `project` — the local project, and the files an agent session reads [Section titled “project — the local project, and the files an agent session reads”](#project--the-local-project-and-the-files-an-agent-session-reads) Everything under `project` writes into the current directory. `project init` scaffolds the project; `project types`, `project grounding` and `project adopt` generate the files a Claude Code session reads before it starts working, and `project skills` keeps the platform’s own skills in `.claude/skills` current — the scaffolded session hook runs all four every session. ### `project types` [Section titled “project types”](#project-types) ```sh turbobase project types --out types.ts turbobase project types --records-only # skip the OpenAPI half ``` Writes generated TypeScript types for the instance’s catalog and prints `wrote ( lines).`. `--records-only` emits only record-shape interfaces. The OpenAPI half (`/v1/catalog/openapi.json`) is session-gated and a PAT cannot authenticate it, so a headless run prints a note and degrades to records-only rather than failing the whole generation. The record shapes — the half apps generate against — come from `catalog:read` and are unaffected. Until 1.3.x the CLI worked around this by trading the PAT for a session at `/auth/pat-exchange`, which required a `data:read` scope. Both were removed: that session carried the owner’s write access, which is far too much to spend on fetching a schema document. ## `ext` — author, verify, ship, and observe extensions [Section titled “ext — author, verify, ship, and observe extensions”](#ext--author-verify-ship-and-observe-extensions) The extension lifecycle end to end: scaffold with `ext new`, verify offline with `ext test` / `ext lint` / `ext replay`, ship with `ext deploy` / `ext plan` / `ext promote`, then read what ran with `turbobase logs`. `ext install` and `ext publish` are the marketplace ends of the same object. ### `ext new hook` [Section titled “ext new hook”](#ext-new-hook) ```sh turbobase ext new hook --record salesOrder --event before_save \ --template require-field --field memo ``` Writes a hook file under `hooks/` and prints `wrote `. Refuses to overwrite an existing file. Templates: `require-field`, `enforce-format`, `blank`. See [Writing hooks](/extending/writing-hooks/). ### `ext new conduit` [Section titled “ext new conduit”](#ext-new-conduit) ```sh turbobase ext new conduit --source shopify --record order --to netsuite \ --event after_canonicalize_inbound ``` Writes a conduit file under `conduits/` (`2` bridge) and prints `wrote `. `--to-record` defaults to the trigger record type. See [Writing conduits](/extending/writing-conduits/). ### `ext new process` [Section titled “ext new process”](#ext-new-process) ```sh turbobase ext new process --record purchaseOrder --then vendorBill --on-failure rollback ``` Writes a process file under `processes/` and prints `wrote `. `--then` adds a second step that waits for the source’s verdict on the first and reads the id it minted; `--on-failure` defaults to `stop`. See [Writing processes](/extending/writing-processes/). ### `ext test` [Section titled “ext test”](#ext-test) ```sh turbobase ext test hooks/customer.before_save.ts turbobase ext test hooks/customer.before_save.ts --reporter junit > results.xml ``` Runs the extension against every fixture in `samples/` through the **same isolated-vm sandbox** production uses. Human output is one `PASS`/`FAIL` line per sample plus an `N/M sample(s) passed.` summary; exits non-zero on any failure. `--reporter junit|json` emits a machine-readable artifact for CI. See [Sandboxes and testing](/extending/sandboxes-and-testing/). ### `ext lint` [Section titled “ext lint”](#ext-lint) ```sh turbobase ext lint conduits/shop2ns.order.ts turbobase ext lint conduits/shop2ns.order.ts --ci ``` Offline static analysis of a hook, conduit or process for the semantic foot-guns the Zod schema can’t catch. No instance / DB / network. `--ci` exits non-zero when any warning fires. Each rule applies to the kinds it is actually about. The deploy-identity check — your module’s own `id` must be the first `id:` literal in the file — applies to all three. The wiring checks (weak `idempotencyKey`, missing `createdFrom`, extreme `cycleBudget`, a same-source “conduit”) describe a cross-source bridge, so they apply to a conduit only. ### `ext replay` [Section titled “ext replay”](#ext-replay) ```sh turbobase ext replay conduits/shop2ns.order.ts --fixture samples/order.json --trace ``` Drives a conduit through its lifecycle (dispatch guards → `from.when` → `transform` → apply-branch → bindings) in dry-run, against a JSON fixture (offline, default) or `--against sandbox` (online, requires a local DB). `--trace` emits the per-stage trace; `--reporter` emits one case per stage. ### `ext deploy` [Section titled “ext deploy”](#ext-deploy) ```sh turbobase ext deploy hooks/customer.before_save.ts # single file turbobase ext deploy --to prod # whole bundle ``` Single-file mode parses the extension and `POST`s it; prints `deployed → status= (new|replaced existing).`. The id is the first `id: '…'` literal in the file; when the module defines a different `id` the deploy is refused (`extension_id_mismatch`) and the CLI names both ids. Whole-bundle mode (`--to`) applies `turbobase/bundle.json` via `/v1/config/apply` and prints `applied bundle to : + ~ -`. A non-admin PAT gets a 403. See [Deploy, plan, promote](/extending/deploy-plan-promote/). ### `ext plan` [Section titled “ext plan”](#ext-plan) ```sh turbobase ext plan --to prod ``` Prints a terraform-style diff of the local bundle vs the target env’s live config — **no writes**: ```plaintext plan against prod: + hook ns:customer:require-name ~ conduit shop2ns:order 1 to add, 1 to change, 0 to destroy. ``` ### `ext promote` [Section titled “ext promote”](#ext-promote) ```sh turbobase ext promote --from sandbox --to prod --confirm acme ``` Promotes the bundle behind a **fail-closed** confirm-slug gate: if `--confirm` doesn’t match the target instance’s slug, nothing is POSTed. On success prints `promoted → (): + ~ -`. ### `ext export` [Section titled “ext export”](#ext-export) ```sh turbobase ext export ``` Snapshots the live instance’s deployable surfaces (hooks, conduits, sync fields/tables, schedules) into `turbobase/bundle.json` and prints `wrote turbobase/bundle.json ( lines).`. The bundle is your config-as-code source of truth that `plan` / `deploy --to` / `promote` ride. ### `ext binding` [Section titled “ext binding”](#ext-binding) ```sh turbobase ext binding --status divergent turbobase ext binding --retry bnd_123 # admin-only re-enqueue ``` Lists `txn_source_link` bindings (filter by `--status` = `ok|pending|blocked|divergent|muted`) or, with `--retry `, re-enqueues a divergent/blocked binding’s fan-out write. `--retry` requires an admin PAT (403 otherwise); a non-retryable binding returns 409. See [Writing conduits](/extending/writing-conduits/#inspecting-and-repairing-bindings). ### `ext install` [Section titled “ext install”](#ext-install) ```sh turbobase ext install acme-recipes@1.2.0 turbobase ext install acme-recipes --connection conn_123 # bind a connection ``` Fetches a published bundle from the marketplace and deploys it with `provenance:'marketplace'` (lands active). If the manifest declares a `{ type:'connection' }` input you must pass `--connection ` to bind one of your instance’s connections. Needs the registry credential — `TURBOBASE_REGISTRY_URL` + `TURBOBASE_REGISTRY_TOKEN`, **both**, from the same place. Ask Turbobase support to issue a registry token for your instance; it is separate from your PAT and from your instance’s internal credentials, and can be revoked on its own. The CLI will not pair one variable with a credential it found elsewhere in your environment, and the URL must be `https://` (loopback excepted) because the token travels to it as an `Authorization` header. See [Marketplace](/extending/marketplace/#the-registry-credential). ### `ext publish` [Section titled “ext publish”](#ext-publish) ```sh turbobase ext publish hooks/recipe.ts --name acme-recipes --pkg-version 1.0.0 \ --manifest manifest.json ``` Publishes an authored extension to the public marketplace. Your instance must be on the **publisher allowlist** (403 `not_a_publisher` otherwise); a duplicate version returns 409. A published bundle is **connection-agnostic** — the connection it touches is bound at install time, never baked in. Needs the same registry credential as `ext install` — see [Marketplace](/extending/marketplace/#the-registry-credential). ## `apps` — hosted apps served from your instance [Section titled “apps — hosted apps served from your instance”](#apps--hosted-apps-served-from-your-instance) A hosted app is a static single-page app that Turbobase serves from inside your instance at `/a/`. Because it is same-origin, it inherits the instance’s auth: no sign-in page, no callback, no CORS, no app-owned keys. The build runs on **your** machine — nothing is built server-side — and the CLI uploads the result. The whole group authorises on one scope, `extensions:deploy`, and additionally requires the caller to be an admin *at the time of the call*, so a demoted admin’s still-valid token cannot deploy. ### `apps create` [Section titled “apps create”](#apps-create) ```sh turbobase apps create reorder-desk --name "Reorder desk" ``` Registers the app so a build can be shipped to it. Required before the first deploy, unless you pass `apps deploy --create`. New apps are private until you share them. The slug **is** the URL and is fixed once created — nothing redirects the old one, so to change it, create a new app. ### `apps init` [Section titled “apps init”](#apps-init) ```sh turbobase apps init reorder-desk ./reorder-desk ``` Scaffolds the project locally — Vite + React + TypeScript, an auth-wired client, a starter read that respects row-level security, and a dev proxy so `localhost:3000/a//` behaves same-origin. Unless you pass `--no-claude` it also writes `CLAUDE.md`, a `0600` `.mcp.json`, and the `preview-app` / `ship-app` skills. It writes files only — nothing is created on the instance, and it works signed out (with placeholders). ### `apps push` [Section titled “apps push”](#apps-push) ```sh turbobase apps push reorder-desk ./reorder-desk --note "tighten the filters" ``` Records the local tree as a new source revision so the **instance** holds the source of record and the app can be pulled from another machine. Source only — it does not build and does not change what is live. Every push appends a revision; nothing is overwritten. `apps deploy` records source too, from the same directory and through the same collector, so this verb is for recording WITHOUT deploying: a tree you want stored before it is ready to go live, or a deploy you ran with `--no-source`. It is also what supplies the knowledge ingest for a `--no-source` deploy. The findings a deploy reads are the ones in the newest recorded revision, so push before deploying whenever you have edited `INSTANCE-LEARNINGS.md` or `TURBOBASE-FEEDBACK.md` and are not letting the deploy record them for you. ### `apps deploy` [Section titled “apps deploy”](#apps-deploy) ```sh turbobase apps deploy reorder-desk ./reorder-desk turbobase apps deploy reorder-desk ./reorder-desk --preview --label "new filters" turbobase apps deploy reorder-desk ./reorder-desk --replace ``` Builds and cuts a new live version at `/a/`. With `--preview` the build is served at its own URL and `/a/` is left untouched — see below. `--preview` opens a NEW preview URL every time, so the second build of the same change is a second link and whoever was sent the first one is still looking at the old bytes. `--replace` re-deploys onto an existing preview instead: the URL, and the label it carries, are unchanged. Pass the handle (`--replace `, from `apps preview list`) or omit it when the app has exactly one open preview — with several open, the CLI lists them and asks which. `--replace` implies `--preview`, keeps the reviewed-but-superseded build in deploy history, and resets the 7-day expiry, so it is also how you bring an expired preview link back. Two deploys of the same app may run at the same moment. Each takes its own version number and keeps its own copy of the files, so a CI job does not have to serialise them. Which one ends up at `/a/` is decided by whichever FINISHES last, not by whichever you started first — so when the order matters, still deploy one after the other. **A deploy from a source directory also records that directory as the app’s newest source revision**, through the same collector `apps push` uses. The version is cut first and the source recorded after it, so a collection that fails costs you the revision and never the deploy — it prints `recorded N source files on the instance (rev R)`, or a line beginning `source not recorded:` naming what to do. Credential files are withheld by name on stderr (`.env`, `.env.*` and `.mcp.json`; `.env.example` is a template and travels), and `node_modules/`, `dist/`, `build/`, `.git/` and `.claude/` are skipped, so what lands is the project rather than its output. Pass `--no-source` to cut the version and upload nothing from the working tree. Nothing is recorded from a directory with no `package.json` either — a prebuilt bundle has no source tree — nor from one this command pulled the source into, which is already the newest revision. An app with no source revision cannot be changed from a user’s in-app change request: there is no copy on the instance to edit, and a built bundle cannot be turned back into a project. App Management says so per app, and the widget tells the person who filed the request. A live deploy also queues the knowledge ingest, and prints which source revision it queued it against — it reads what the recorded source holds, not the bundle this command just built. It warns when the app has never been pushed, and when your local `INSTANCE-LEARNINGS.md` / `TURBOBASE-FEEDBACK.md` are newer than that revision. ### `apps preview list` / `apps preview discard` [Section titled “apps preview list / apps preview discard”](#apps-preview-list--apps-preview-discard) ```sh turbobase apps preview list reorder-desk turbobase apps preview discard reorder-desk ``` Previews expire after **7 days**; `list` shows them newest-first with each URL and expiry date. A preview URL grants no new access — it opens only for people who could already open the app. `discard` stops the URL resolving; the build stays in deploy history and can still be promoted. ### `apps promote` [Section titled “apps promote”](#apps-promote) ```sh turbobase apps promote reorder-desk ``` Makes a preview the live version. **Nothing is rebuilt** — the bundle’s asset URLs name the build rather than the page it is served from, so promotion is a pointer write and the reviewed bytes are the shipped bytes. Promotion also fires the effects a preview deliberately skips: applying the manifest’s name and description, the release ledger, relationship activation, proposal completion, and knowledge ingest. It also applies the manifest’s declared roles — the capabilities they gain and any `scopes` change — and prints what changed, so a Slack channel a role loses is in the promote output, not only in the plan. ### `apps pull` [Section titled “apps pull”](#apps-pull) ```sh turbobase apps pull reorder-desk ./reorder-desk turbobase apps pull --proposal ``` Writes the app’s newest source revision to disk — whether it was generated from a proposal or pushed by you. Read-only; it never deploys. With `--proposal` the app is derived from the proposal, and its request context is written alongside the source. ### `apps list` [Section titled “apps list”](#apps-list) ```sh turbobase apps list turbobase apps list --json ``` Every hosted app with whether it is live, its latest source revision, and its audience. A `—` in the source column means the app was deployed but never pushed, so there is nothing to pull. ## `kb` — write findings into the knowledge base [Section titled “kb — write findings into the knowledge base”](#kb--write-findings-into-the-knowledge-base) ### `kb push` [Section titled “kb push”](#kb-push) ```sh turbobase kb push --dry-run turbobase kb push ``` `turbobase apps push` uploads your standing markdown and parses it into a pending queue on the instance. `kb push` is the only thing that turns those findings into knowledge-base pages — recording what you learned and changing the company’s documentation are deliberately separate decisions. It re-reads your pushed markdown before planning and prints what that found: ```plaintext 2 file(s) scanned · 1 changed · 6 new finding(s) · 15 already known ``` Read that line before anything else. `0 file(s) scanned` means your markdown never reached the instance — you deployed without pushing, and `apps deploy` uploads the built bundle, which contains no `.md` files at all. `15 already known` means your edit landed and those findings were already dealt with; a finding’s identity is its normalized text, so reformatting, renumbering or re-heading one is deliberately the same finding. The unit is a **page, not a finding**: a dozen findings about one page become one appended section and one write, so you approve “19 pages”, never “53 things”. The plan is printed in full before anything is written, and the command asks. New pages land **unpublished** so a human can fold them into the taxonomy; existing pages are appended to, never rewritten; and a page whose unpublished work belongs to someone else is skipped rather than overwritten. `--dry-run` prints the plan and exits. `--yes` skips the prompt; without it, a non-interactive run refuses rather than assuming. If the queue moves while you are reading the plan, the write is rejected and nothing lands. Grouping is a judgement — two findings that name the same subject are assumed to be about the same page. When they are not, `--no-group` plans every finding on its own: the same pages are targeted, but N findings for one page become N sequential appends instead of one merged block. The plan also warns when two NEW pages look like the same subject written two ways; it never merges them for you. A **correction** whose page ref matches no page is skipped rather than turned into a new page — a correction needs a page to correct. The plan names the ref that failed, and those findings stay pending until you fix it. A skipped group is counted and shown as a skip throughout: it is not in the “N page(s)” tally, it gets no write-set under `--diff`, and it is not in the numbers the confirmation prompt quotes. If everything in scope is skipped there is nothing to confirm, so you are not asked. ## `skills` — write standing rules into the instance’s agents [Section titled “skills — write standing rules into the instance’s agents”](#skills--write-standing-rules-into-the-instances-agents) ### `skills push` [Section titled “skills push”](#skills-push) ```sh turbobase skills push --dry-run turbobase skills push ``` The other half of the same queue. An authoring session records two kinds of finding: the narrative that should be *findable* when someone asks the right question, and the hard rules that must apply on **every** turn whether or not anyone thinks to ask. `kb push` writes the first kind into the knowledge base; `skills push` writes the second as agent skills. Rules under one `###` sub-heading become ONE skill, named after that heading. The plan is printed in full before anything is written; `--dry-run` prints it and exits, `--yes` skips the prompt, and without it a non-interactive run refuses rather than assuming. Like `kb push`, it re-reads your pushed markdown first and prints what that found. #### `--reapply` — landing a corrected grouping [Section titled “--reapply — landing a corrected grouping”](#--reapply--landing-a-corrected-grouping) A finding’s identity is its normalized **text**, so re-filing a rule under a different `###` heading is deliberately the same finding: it queues nothing, and without `--reapply` there is nothing for a push to act on. That is the right default — the queue is a work list, not a history — but it means a grouping you fixed after the first push cannot reach the instance on its own. `--reapply` re-emits rules already applied, so the new grouping (and any body text you tightened) lands. It is safe to run more than once: the write is keyed on the skill’s slug, a finding already present in a rule is not appended twice, and a finding you **dismissed** stays dismissed — that status is the one a human set deliberately to mean no. Rules land **draft and disabled**, and there is deliberately no flag to change that. A PAT that can deploy an app is not thereby authorised to change what every agent on the instance is told. Publishing is a separate act on its own opt-in scope — `turbobase skills publish`, or the Skills page in the app. ### `kb list | publish | unpublish | versions | rollback | delete` [Section titled “kb list | publish | unpublish | versions | rollback | delete”](#kb-list--publish--unpublish--versions--rollback--delete) ```sh turbobase kb list turbobase kb publish month-end-close turbobase kb unpublish month-end-close turbobase kb versions turbobase kb rollback 12 turbobase kb delete month-end-close ``` The knowledge-base editor, from a terminal. All six need a PAT carrying **`docs:publish`** — a dedicated, opt-in scope that a token minted before this release will not have. `kb push` is unchanged and still runs on `extensions:deploy`: filing a draft and arming what every reader (and every AI answer) sees are different powers, so they carry different keys. `kb list` reports whether each page is **actually readable**, not just its visibility flag. A page flipped to published but never included in a release is approved text nobody can find, and it is the single most confusing state the knowledge base has. `kb publish` is one act: it sets visibility **and** cuts a release scoped to the pages you name, so the page is live when the command returns and publishing one page cannot ship a colleague’s half-written one. `kb unpublish` is the exact inverse and takes effect immediately. `kb delete` is **soft** — the page and its subtree drop out of the tree and out of every reader release, and stay restorable from the knowledge base’s trash. This differs from `skills delete`, which is permanent, and the asymmetry is deliberate: a skill’s text survives in every release that carried it, while a page is the only copy of prose a human wrote. ## `release` — ship your project from your own CI [Section titled “release — ship your project from your own CI”](#release--ship-your-project-from-your-own-ci) Your repo, your runner, your credential. `release deploy` uploads the bytes in your checkout; Turbobase clones nothing and holds no GitHub App key. The only credential is a PAT you mint with the `releases:write` scope. `turbobase project ci` scaffolds a GitHub Action that runs exactly this, and the CLI is the equal front door — neither is privileged over the other. ### `release deploy` [Section titled “release deploy”](#release-deploy) ```sh turbobase release deploy --target auto --project . --ref HEAD --follow ``` Uploads `<--project>/src/` as `{path → contents}` and enqueues the server-side deploy. `--target auto` applies immediately; `--target approved` fails closed with `403 approval_required` unless `--approved-by ` records an approval. Omitting an SDF `src/` requires `--solution ` (the live-fetch path). `--ref`, `--git-repo`, `--git-ref` and `--pr-url` are **provenance links only** — recorded against the release, never dereferenced. `--ref` is resolved locally with `git rev-parse`, so a branch, tag or short sha all normalise to a full one. They default from `$GITHUB_SHA` / `$GITHUB_REPOSITORY` / `$GITHUB_REF` / `$PR_URL`, so a CI run fills them in with no flags. Anything that can’t be derived is simply left null and never blocks the deploy. `--follow` polls to completion and exits non-zero if the deploy fails. ### `release status` [Section titled “release status”](#release-status) ```sh turbobase release status rel_abc123 --follow ``` Prints the release’s current stage and percent, or streams to completion with `--follow`. ### `release rollback` [Section titled “release rollback”](#release-rollback) ```sh turbobase release rollback rel_abc123 ``` Server-side reverse deploy, LIFO-guarded: a release that is not live, or that a newer release has advanced past, is refused with 409 rather than rolled back. ### `release list` [Section titled “release list”](#release-list) ```sh turbobase release list ``` Releases newest-first with delivered titles and latest status. ## `sandbox` — ephemeral local instances [Section titled “sandbox — ephemeral local instances”](#sandbox--ephemeral-local-instances) A sandbox is a throwaway database seeded with a sampled, redacted slice of a real instance — somewhere to run `ext replay --against sandbox` without going near production data. **`sandbox create` is not available yet**: it refuses and creates nothing. Seeding needs a per-column PII classification for the source instance’s tables, and redaction fails closed on any column it cannot prove is safe. `ext test` and `ext replay --fixture` are the offline paths that work today. ### `sandbox create` [Section titled “sandbox create”](#sandbox-create) ```sh turbobase sandbox create --from acme --ttl 72h --sample 2% ``` Stands up a fresh **local** authoring sandbox seeded with a sampled + redacted slice of `--from`, mounts the working tree’s `hooks/` + `conduits/`, and prints the sandbox name, source, URL, expiry, and mount counts. The sandbox process forces `TURBOBASE_SANDBOX=1` so every source resolves to a mock, so no code path reaches a real Oracle NetSuite or Stripe account. ### `sandbox list` [Section titled “sandbox list”](#sandbox-list) ```sh turbobase sandbox list ``` Lists active sandboxes (`name from=… expires=… url`) and opportunistically reaps any past their TTL. ### `sandbox destroy` [Section titled “sandbox destroy”](#sandbox-destroy) ```sh turbobase sandbox destroy acme-72h-abc ``` Drops the sandbox database and removes it from the registry; prints `destroyed sandbox (dropped ).`. See [Sandboxes and testing](/extending/sandboxes-and-testing/) for the two distinct senses of “sandbox” (the code sandbox vs. an account sandbox). ## `guardrails` — decide which write-backs are allowed to leave [Section titled “guardrails — decide which write-backs are allowed to leave”](#guardrails--decide-which-write-backs-are-allowed-to-leave) ```sh turbobase guardrails posture # the global default turbobase guardrails list # every rule, in evaluation order turbobase guardrails create "open invoices" --source netsuite --record invoice --decision allow --priority 10 turbobase guardrails test --source netsuite --record invoice # what would happen to this write turbobase guardrails deactivate "open invoices" # park it, reversibly ``` The same rules the **Compliance → Guardrails** page shows, from the command line. `posture` is the one global switch: `allow` makes the rules a deny-list, `deny` makes them an allow-list. Everything else is per rule — `create` a rule, `edit` its decision or priority, `activate` or `deactivate` it, `delete` it. `test` is the one to reach for before you change anything: it runs the same evaluator the write path runs, against a write you describe, and writes nothing. It exits 1 when the write would not proceed, so your own CI can gate on it. Guardrails sit **under** the per-source write entitlement and cannot open a write path your plan does not include. First match wins, lower priority is evaluated first, and a delete is gated separately from a write. ## `relationships` — which linked record pairs re-read each other [Section titled “relationships — which linked record pairs re-read each other”](#relationships--which-linked-record-pairs-re-read-each-other) ```sh turbobase relationships list # every pair, and which re-read is on turbobase relationships list --source netsuite # one connected system turbobase relationships refresh cr_delivery_line:custrecord_line_delivery:cr_delivery --children --on turbobase relationships refresh cr_delivery_line:custrecord_line_delivery:cr_delivery --parent --off ``` Some systems save a parent’s **lines** as part of the parent’s own save and raise no event on the lines, so the parent reaches your instance in seconds and its lines wait for the scheduled catch-up. The mirror image happens too: saving a line makes the system silently rewrite totals on the parent. Turbobase can close either gap by re-reading the other side, and these two verbs are how you switch that on. The app does not list them: a record on **Data → Records** carries a re-read mark when one of its pairs has a re-read switched on, and these verbs are where the three names, the time and the switch itself live. `list` prints one row per pair your instance has discovered: the line table, the field on the line that holds its parent, the parent table, and each of the two re-reads as `on` — with **when** it was switched on — or `off`. An empty list is a fact about discovery rather than about the behaviours: a pair appears once a source is reconciled. `refresh` takes the pair as one argument, `CHILD:KEY:PARENT`, exactly as `list` prints the three names. Then say which behaviour and which way — `--children` (re-read the lines when their parent is saved) or `--parent` (re-read the parent when one of its lines is saved), and `--on` or `--off`. Both halves are required: nothing is defaulted, because a default would switch a behaviour you did not name. A pair your instance has not discovered is refused and the refusal names what *is* declared on that line table — nothing is created here. Replaying a call that changes nothing says so, and leaves the original time alone. **Each switched-on pair has a running cost** — one query to the connected system per parent save, plus one re-read per line — so switch on the pairs that are actually arriving late (`turbobase logs`, and the **Late arrivals** page, say which) rather than all of them. Both verbs need a token with the `extensions:deploy` permission and an administrator behind it. ## `tables` — custom tables of your own [Section titled “tables — custom tables of your own”](#tables--custom-tables-of-your-own) ```sh turbobase tables list # the custom tables on your instance turbobase tables create expenses -f amount:number -f spent_on:date turbobase tables plan # what this project's manifest would do turbobase tables apply # apply it turbobase tables drop expenses --confirm expenses ``` Tables you add alongside your mirrored records, for the data your business keeps that no connected system holds. They are the CLI twin of the **New custom table** button on the Records page, and they behave the same way: a table is additive, so applying a manifest gives an existing table the fields you declare and leaves the fields other projects declared alone. `plan` writes nothing and exits 1 with a conflict report when another claimant already declares one of your field names at a different type — run it in CI and a clash is caught before the deploy. `drop` deletes the table and every row in it, and will not run unless `--confirm` matches the slug exactly. ## `logs` — every log, under one noun [Section titled “logs — every log, under one noun”](#logs--every-log-under-one-noun) ```sh turbobase logs --since 10m # everything, last 10 minutes turbobase logs --subsystem guardrails --severity warn turbobase logs --correlation-id 5f3c… # one write, across subsystems turbobase logs --follow # poll for new rows turbobase logs --extension ext_abc123 # was `ext logs ext_abc123` turbobase logs --conduit cnd_xyz --follow # was `ext logs cnd_xyz --follow` turbobase logs --process-run 1111… --follow # one process run, until it finishes ``` All log access under one noun. With no target flag this reads the unified platform event log (`GET /v1/events`) — guardrails, hooks, scheduled tasks, conduits and sync in one stream, one envelope, one correlation id. One line per row: timestamp, severity, outcome, event code, where it happened, the correlation id, the typed detail, and a `redacted=[…]` marker naming which redaction rule groups fired (never what they matched). `--severity` is a **threshold**, not an equality filter: `warn` includes `error`. `--since` takes a relative window (`10m`, `2h`, `3d`) or an ISO timestamp. `--follow` polls every `--interval-ms` (default 2000) from a cursor, so it never re-prints a row. `--extension ` reads that extension’s bounded log ring buffer and `--conduit ` reads that conduit’s `conduit_event` run ledger — the two modes the removed `ext logs` had. Each stays its own read rather than a filter, because each is the system of record for its subsystem and the platform log is derived from it. `--process-run ` is the third, and it is the one that ENDS. A conduit has no end, so `--follow` on one polls until you interrupt it; a process run reaches a terminal state, so following one prints each step as it lands and returns when the run finishes. Following a run is a flag here rather than a `processes logs` verb because all log access unifies under one noun. Rows are redacted at WRITE, so secrets, absolute paths, stack frames and SQL never reach the stored row for anyone — while your hook’s rejection messages, your guardrail reasons and your `custbody_*` / `cr_*` / `cf_*` ids survive verbatim. The log is sampled (high-volume events carry an `occurrences` count) and expires: 90 days for `error`, 30 for `warn`, 7 for `info`, 1 for `debug`. ## `processes` — what runs in the background [Section titled “processes — what runs in the background”](#processes--what-runs-in-the-background) ```sh turbobase processes list # what is deployed, and how it fires turbobase processes runs acme:reorder-suggestions # that process's whole history turbobase processes run 1111… # one run and its step ledger turbobase processes invoke acme:reorder-suggestions --input '{"warehouse":"east"}' # start one turbobase processes cancel 1111… # stop it turbobase processes rollback 1111… # undo what a finished run created ``` `processes list` is the answer to “is the nightly job actually scheduled?” — it prints each process’s trigger as `manual`, or as `scheduled` with **both** the cron expression and the timezone it is read in, because `0 2 * * *` is a different moment in `Europe/London` and in `America/New_York`. A process an administrator has switched off is marked `[off]`, and each row carries its last five runs with state, start and duration. `processes runs ` is the whole history rather than those five, and `processes run ` opens one run: every step, its disposition, the record it wrote and the refusal that stopped it. `processes invoke ` starts a run, exactly as an app’s call to `POST /v1/processes/:id` does. Pass the input with `--input ''` or `--input-file ` — a JSON object, sent as the whole input and checked against the schema the process declares; with neither, the input is `{}`. By default the run is queued and the command prints its id; add `--sync` to wait for it and print its state, anything still outstanding, and each step’s disposition. A synchronous wait is bounded by the instance’s budget: a run that outlasts it is **still running, not failed**, and the command prints its id and how to watch it. The run is the token owner’s — it writes as that person, and the token must carry `extensions:deploy` and belong to an administrator. `processes cancel ` stops a queued run before it executes, and stops a running one **at its next step boundary** — the step in flight finishes its write rather than being killed halfway through, and what already went upstream stays. A cancel is not a failure, so nothing is rolled back. `processes rollback ` undoes a run that has **finished** — committed, failed or cancelled. It deletes, newest first, only the records the run’s own ledger shows it created; a record it updated, a row an earlier run had already migrated, and a step declared `rollback: 'keep'` are left alone. A run still queued or running is refused: cancel it first. Rolling back a run that is already `rolled_back` does nothing. The deletes reach your connected system at the instance’s rollback pace rather than all at once, so a large run’s `reason` says its deletes are still being sent until they are; if the source refuses one, that record comes back and the run reads `failed` with the refusal named. To watch a run as it goes, use the log noun: `turbobase logs --process-run --follow`. ## `data` — act on one record [Section titled “data — act on one record”](#data--act-on-one-record) ```sh turbobase data settle nonInventorySaleItem 2b7c… # link the row to the record the source already created ``` `data settle` is the way out of a `write_settle_conflict`: the connected system **created** the record and handed back its id, and linking that id onto the row here failed, so the row reads as unsynced over a record that exists. Saving the row again would create a second record upstream; this links it instead. It reads the id from the row’s `record_write_state` (never from the command line), discards the inbound copy of the same record if one arrived meanwhile — only an untouched one; a copy someone edited is left alone and the command refuses with `409` — marks the row synced and resolves the failure. Running it again on a row it already linked answers the same success. It needs a token with the `rest:write` permission, and only links a row its owner could write in the app. ## `mcp` — the local authoring server [Section titled “mcp — the local authoring server”](#mcp--the-local-authoring-server) ```sh turbobase mcp --base-url https://acme.turbobase.app ``` Runs the local stdio authoring MCP server so Claude Code can drive the same library functions the CLI does. Not usually a command you type: it is the process `.mcp.json` spawns, launched on demand by the file `project init` generated. See the [overview](/cli/overview/#author-with-claude-code--mcpjson-and-turbobase-mcp). # Key concepts A single reference for the named pieces of Turbobase, the ERP operations and development platform for Oracle NetSuite. Read this once and the rest of the docs read straight through. > New here? Start with [Getting started](/getting-started/what-is-turbobase/) for the path to a live instance, then come back to this page for how the pieces fit together. Every word it uses is defined once, on the [Glossary](/getting-started/glossary/). If you only have ten minutes: * A **source connector** plugs a system of record (NetSuite, Stripe, and others) into your instance via a small, fixed contract. * The **sink** is your Postgres — every source flows into one canonical schema you own. * A **sync event** is one row’s trip in either direction; a **sync failure** is an event that didn’t land. * **Hooks** shape outbound writes (validate, rewrite); **guardrails** gate privileged operations (allow, audit, confirm, deny). * **Atlas** consolidates the same entity across multiple source systems. * **Tasks** are scheduled jobs — chat prompts, saved views, system maintenance — your instance runs on a cron. * **Channels** deliver human-in-the-loop notifications (Slack, …) for confirmations and alerts. * The **audit log** is one append-only table that records every privileged op and decision. The rest of the page expands each. *** ## Source connector [Section titled “Source connector”](#source-connector) A pluggable link between Turbobase and one external system. The contract is small enough to fit in a paragraph; the engine, queue, conflict resolver, named agents, hooks, guardrails, and chat UI never branch on which connector is attached. A connector implements five methods, give or take: | Method | Purpose | | ----------------------------- | --------------------------------------------------------------------- | | `verifyWebhookSignature(req)` | Confirm an inbound webhook came from the source (HMAC, OAuth, etc.). | | `parseEnvelope(body)` | Normalise the source’s webhook payload into a canonical envelope. | | `writeBack(event, patch)` | Push a canonical patch back to the source system. | | `listChanges(type, cursor?)` | Iterate records modified since a cursor (delta sync). | | `schemaIntrospect(account)` | Snapshot the source’s schema — custom fields, available record types. | Stateful connectors (NetSuite) add lifecycle hooks for governance, auth routing, and session-expired UX. Stateless connectors (Stripe) skip most of those — they’re webhook-led with a single-account API key. Both shapes ship today and serve as the reference for new connectors. Connectors that are not yet live ship through a managed onboarding flow rather than a public extension surface. Email if you need a source we don’t list. *** ## Third-party system integration [Section titled “Third-party system integration”](#third-party-system-integration) Two paths run in parallel for every connector: * **Source → your Postgres (inbound).** The source emits a webhook (or the engine pulls deltas); the envelope is verified and queued; the canonicalizer projects the source-shaped record onto your canonical schema. * **Your Postgres → source (outbound write-back).** An app write marked `originating_system = 'hybrid'` triggers the realtime listener; hooks fire; the connector pushes to the source. A **standalone instance** (`source_system='standalone'`) is the degenerate case: Turbobase is the system of record, webhook ingress and write-back both no-op. The schema, RLS, hooks, guardrails, audit log, channels, and chat UI are unchanged. *** ## Sink (the canonical Postgres mirror) [Section titled “Sink (the canonical Postgres mirror)”](#sink-the-canonical-postgres-mirror) The Postgres database every source writes into and every read serves from. “Sink” is the data-flow term; the rest of the docs call the same thing your **canonical mirror** — one concept, two vantage points. There’s exactly one per instance, and you own it. * Schema namespace: `turbobase` (never `public`). More than two hundred tables today, spanning customers, sales orders, invoicing, fulfillment, payments, items, vendor bills, purchase orders, journal entries, accounting periods, chart of accounts, projects, and the supporting lookups and line tables. * Every record carries `source_system`, `external_id`, `last_modified_date` (when the source last changed it), `last_modified_pg`, `originating_system`, `synced_at` and `sync_version` — enough metadata to reconstruct provenance and resolve conflicts. A record you can create in Turbobase also carries a `pg_row_id` of its own, so it exists before the source has given it an id. * Reads exit through PostgREST and Realtime; writes that need a round-trip to the source go through the write-back queue. * Row-level security scopes every PostgREST call to the calling user (`has_capability`, `scopes_match`). The anon key never bypasses RLS. *** ## Sync engine: events, failures, conflict resolution [Section titled “Sync engine: events, failures, conflict resolution”](#sync-engine-events-failures-conflict-resolution) The generic core that drives both directions. It doesn’t know what NetSuite or Stripe is — it knows about connectors, canonical patches, delta cursors, and queues. * **`sync_event`** — one row per record-trip. `direction` is `source_to_pg` or `pg_to_source`. State machine: `pending → in_flight → committed | failed`, with two sidings — `awaiting_confirmation` while a guardrail holds the write for someone to decide, and `quarantined`. * **`sync_failure`** — emitted when an event fails. Carries category, classification, the offending payload, and the connector’s error. The Mechanic agent subscribes to this table over Realtime. * **Delta cursor** — a per-record-type `lastModifiedDate` checkpoint. The cursor only advances on a clean run; a partial run safely re-scans the same window. * **Conflict resolver** — `last_modified_pg` against the last sync touch (`synced_at`) on one side, and the timestamp the source itself reports on the inbound record on the other, decide whether both sides changed in the same window. Latest write wins; on a tie the source does. Per-field ownership rules resolve which side wins on a per-column basis. *** ## Hooks [Section titled “Hooks”](#hooks) Hooks intercept write-backs before they leave for the source. Two phases: * **`validate`** returns validation errors. A non-empty list short-circuits — the event becomes a `sync_failure` with `category='hook_validation'`. * **`rewrite`** returns a new canonical patch. Composes left-to-right; the next hook sees the previous one’s output. Hook *kinds* are code; hook *rows* are admin-defined and instance-wide, selected by record type. RLS gates writes to admins only; a default guardrail also denies non-admin chat writes to the hook table. Shipped kinds include `require-field` (fail when a top-level canonical field is missing), source-specific arithmetic helpers (for example, NetSuite line `amount = quantity × rate` when missing), and `custom-validator` / `custom-rewrite` — admin-supplied JavaScript run in a sandboxed isolate with strict heap and wall-clock limits. Hooks also have **provenance** — `code-baseline` (**Code baseline**, shipped with Turbobase), `operator` (**CLI deploy**, what you deployed yourself), `mechanic` (**Mechanic**, learned from a real sync rejection) or `learning` (**Learning**, raised proactively) — which feeds the learning loop (see *Learning mode* below). It is the **Origin** column on the extensions page, and you can filter on it. *** ## Guardrails [Section titled “Guardrails”](#guardrails) A policy engine that gates **privileged operations** — anything that mutates source-side configuration (custom fields, role permissions, deployment surface) or pushes high-value writes (large dollar amounts, AI-driven mutations on sensitive fields). Where hooks shape the *content* of a write, guardrails decide whether the *operation itself* runs at all. Every privileged op declares a descriptor: ```ts { source: 'netsuite', op: 'customfield.delete', risk: 'destructive', target: 'customrecord_my_table.custrecord_signing_key', actor: 'agent:mechanic' } ``` The engine resolves one of four decisions: | Decision | Effect | | ------------------ | ------------------------------------------------------------------------------------ | | `allow` | Execute, no audit row. | | `allow_with_audit` | Execute, write an audit row (the default for most ops). | | `require_confirm` | Block, write a pending-confirmation row, fan out via channels, wait for an operator. | | `deny` | Refuse, write an audit row with `status='denied'`. | Policy is layered per source × per op-pattern × per risk × per actor. Defaults ship out of the box; admins layer instance-specific rules on top from the app. First match wins; the catch-all is the per-risk default. The headline use case is *“AI can’t update salesorder.amount, humans can”* — same op, different actor, different decision. *** ## Audit log [Section titled “Audit log”](#audit-log) One append-only table — `turbobase.audit_log` — captures every privileged op, every guardrail decision, every authentication event, and every user-management mutation. Written through a `SECURITY DEFINER` function so callers don’t need direct insert grants. Row shape (abbreviated): | column | what it carries | | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `actor` | `wizard:setup` / `cli:` / `agent:` / `user:` | | `action` | Verb. Connector ops use `connector..`; guardrail decisions use `guardrail.*`; auth events use `auth.*`. | | `target_table`, `target_id` | What was acted on. | | `before`, `after` | JSONB snapshots — deletes capture `before`, creates capture `after`, updates capture both. | | `correlation_id` | Confirmation token (when `require_confirm` fired) or caller-supplied id linking related ops. | | `context` | `{ decision, reason, risk, args, result }` — the full guardrail trace. | The `/audit` page in your Turbobase app gives operators a date-range form, quick-filter chips, and per-actor / per-target drill-down. *** ## Tasks (scheduled tasks) [Section titled “Tasks (scheduled tasks)”](#tasks-scheduled-tasks) A cron-like scheduler built into your instance. A worker polls `turbobase.scheduled_task` once a minute, picks rows whose `next_run_at` has elapsed, runs each task as the **owner** (per-run JWT — RLS, scopes, and capabilities all apply), records a `scheduled_task_run` plus a notification, and recomputes `next_run_at` from the task’s schedule. Three task body kinds: | `body.kind` | What it does | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `chat_prompt` | Invoke Pilot, your AI assistant, with a stored prompt — for example, *“Email me yesterday’s at-risk sales orders”*. | | `saved_view` | Re-run a pinned saved view and deliver the result. | | `system_job` | Built-in maintenance job (delta resync, schema-drift detection, playbook rebuild, learning rebuild). No per-user JWT — runs system-owned. | Delivery is either in-app (notification row) or out-of-band via a channel (Slack — see *Channels* below). Five consecutive failures auto-pause the task and notify the owner. The recurring sync jobs are exempt from that five-failure rule — the delta sync keeps its schedule through failure streaks (failures stay visible in the run history and on the sync-health report). The built-in jobs that use AI are exempt too when the only thing missing is an AI key: each keeps its schedule, does the part of its work that needs no AI, records in its run history that it produced no AI output, and starts using AI the moment you add a key. When a recurring platform job is failing because a source refused our sign-in — the scheduled sync itself included — the sync-health report says so on that job’s own row rather than counting it as one more failing job, and tells you to reconnect the source from **Data → Sources**, since a fresh sign-in is the only thing that mints a new credential. Those rows clear themselves on the first run that succeeds; there is nothing to dismiss. Nothing stays broken unnoticed, though: any system job still failing 24 hours after its streak began raises an escalation your operator is alerted on. The two document-memory sweeps (uploaded-document text extraction and embedding) additionally **stop** at that point rather than keep calling a dependency that is refusing them; the reason is recorded on the row, and they stay stopped until support resumes them, because platform jobs are not writable from the tenant surface. The sync jobs are deliberately not stopped — a source outage that ends should not leave your data sync switched off. Constraints plus RLS enforce the `(system=true ↔ owner=null)` split: any authenticated caller can read system rows, only admins or the service role can mutate them. *** ## Atlas (entity consolidation) [Section titled “Atlas (entity consolidation)”](#atlas-entity-consolidation) The multi-source identity-resolution layer. When two sources both emit a *customer* record for the same real-world organisation, Atlas decides whether to link them, create a new canonical entity, or surface the pair for human review. Pipeline (deterministic tier — what ships today): 1. Read identity fields off the canonical payload via the paths declared in the record type’s identity-field map. Seven dimensions can match: `email`, `phone`, `taxId`, `domain`, `gtin` (a product’s barcode), `externalKey` and, for a person, name-plus-employer. 2. Normalise each — lowercase email, E.164 phone, digits-only tax id, and a web address reduced to a bare host. A host that identifies nobody (a free mail provider, say) is dropped rather than matched on, so two unrelated customers who both use one never consolidate. 3. Query for exact matches on each populated key. 4. **Single match** → link. **Multiple matches** → review queue with both candidates. **No match** but at least one identity present → create a new canonical row. **Zero identities** → create new (no keys to dedup on; future embedding tier reconciles). Embedding and LLM tiers are wired but reserved for when dedicated workers ship. **Important:** Atlas consolidates the records that name a *thing* — customer, vendor, contact, employee, partner, and the items you sell (matched on barcode or SKU). Transaction-shaped records (invoice, payment, fulfillment) stay per-source — they’re ledger events, not identities. A future cross-source ledger *bridges* those transactions without collapsing them. *** ## Channels (notification delivery) [Section titled “Channels (notification delivery)”](#channels-notification-delivery) Pluggable fan-out for human-in-the-loop events: * `confirmation_requested` — a guardrail hit `require_confirm`; an operator needs to approve or deny within the configured window. * `confirmation_decided` — somebody approved or denied; the original requester and the other channels get the resolution. * Task failure notifications, scheduled-task delivery, schema-drift alerts. Slack is the channel your instance exposes today: connect it from **Settings → Slack** and it registers at boot. Every `require_confirm` decision ends in a Slack message with the approval link pre-baked. *** ## Agents (the four named cast) [Section titled “Agents (the four named cast)”](#agents-the-four-named-cast) Turbobase ships with four named agents. Each one has a specific job, a specific permission scope, and a specific surface where you talk to it. Future releases extend the cast under the same naming convention — recognisable English job titles. | Agent | Role | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Conductor** | The behind-the-scenes coordinator. Routes events to the right specialist, applies your permission rules, owns notification delivery and skill loading. Long-lived; supervises the others. | | **Mechanic** | Watches your sync, fixes what it can, asks for help on what it can’t. Subscribes to `sync_failure`; resolves known patterns (record locked, insufficient permission, field validation, governance limit, missing dependency) autonomously today, and is designed to grow into bundle drift, role permissions, and schema drift. | | **Pilot** | Drives Turbobase in plain English. Answers questions over the canonical schema, builds apps from natural-language prompts, runs scheduled tasks. The same agent runs in the app and on Slack. | | **Concierge** | Walks the operator through onboarding. Provides click-paths for the source you’re connecting, validates credentials, kicks off the initial sync. | **Why these four (and only these four)** — the cast is small on purpose. Memory, learning, and skills are *traits all four agents share*, not separate agents. Hooks are user-written code, not agents. Guardrails are policy, not agents. New agents added later will get their own English job-title names (Auditor, Watchdog, Archivist, …) so the cast stays legible to a non-technical reader. ### How the four agents handle multi-system sync [Section titled “How the four agents handle multi-system sync”](#how-the-four-agents-handle-multi-system-sync) Every agent works against the *canonical* layer, not source-specific code. That’s what makes a single cast scale across multiple sources instead of multiplying with each new connector. * **Conductor** is source-agnostic by construction. It dispatches events whose `source_system` is just a column. * **Mechanic** operates on failure patterns expressed in connector-neutral terms. “Record locked” covers a NetSuite record-lock today and a Stripe idempotency conflict tomorrow. “Governance limit” covers NetSuite governance windows and Salesforce daily-API caps. * **Pilot** queries the canonical schema over PostgREST plus RLS. It doesn’t know which connector wrote a given row. A question like “show me this customer’s billing across systems” naturally joins NetSuite, Stripe, and Salesforce data once the consolidation lands — no new “multi-source mode” in Pilot. * **Concierge** ships per-source onboarding steps, but the runtime is the same across all of them. Each new connector contributes one step — its credential validator plus introspection call. The same per-instance permission tiers and the same memory (“subsidiary 7 mandates a class on every line”; “this customer’s payment terms are NET 45”) apply across every source your instance has wired up. **You don’t get a per-connector agent farm; you get one cast that learns about your business and applies that knowledge wherever your data lives.** *** ## Permission tiers (AI agent + per-instance) [Section titled “Permission tiers (AI agent + per-instance)”](#permission-tiers-ai-agent--per-instance) How autonomously the Mechanic is allowed to act on a given failure pattern. Three tiers, configurable per instance per pattern: | Tier | Behaviour | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `one_tap` | The agent stages the fix and sends a one-tap approval to the configured channels. **This is the default for every failure kind** — a fresh instance applies nothing on its own. | | `auto_apply` | The agent applies the fix directly. You promote a pattern here once you trust it; your instance also offers to promote one after 20 resolutions it got right with high confidence. | | `escalate` | The agent posts a structured recommendation but does not act. | Tier choices are recorded in the audit log; they layer cleanly with guardrails — a `require_confirm` rule always wins over an `auto_apply` tier. *** ## Skills, playbooks, and learning mode [Section titled “Skills, playbooks, and learning mode”](#skills-playbooks-and-learning-mode) * **Skills** — agent capability bundles. Each bundle packages prompts, tools, and policies for a specific class of problem (for example, “record-locked retries”). Some ship with Turbobase; you can write and publish your own — see [Agent skills](/tenant/skills/). * **Playbooks** — longer operating manuals the agent consults when a skill isn’t pre-baked. Rebuilt nightly from the failure-resolution corpus. * **Learning mode** — a **phase** every instance starts in. While in `learning`, every recurring `sync_failure` cluster becomes a hook *candidate*; admins review on the extensions page and apply, edit, or dismiss. Two kinds of failure can land a hook on their own, above 0.85 confidence and as `provenance='mechanic'`: a locked record and a governance limit. Everything else always comes to you — a field the source rejected, a missing permission, a missing dependency and a refused sign-in are never auto-applied, because each needs a decision only you can make. The top bar shows a soft “Learning” indicator, with a three-item Steady checklist (7 days active, fewer than 2 novel failures in the last week, hooks reviewed). The offer to promote to **Steady** gates on your write error rate rather than on the checklist, so clearing all three does not by itself move you on. What one instance has learned moves to another: `turbobase ext export` pulls your hooks down into a project, and deploying that project into a second instance carries them over — so a sandbox’s learnings can promote to a fresh production instance. *** ## Proposals, solutions, and releases [Section titled “Proposals, solutions, and releases”](#proposals-solutions-and-releases) The pipeline for changing your instance. A **proposal** is a drafted, evidence-cited change; you shape it conversationally with the AI in **Studio**, the chat-first authoring canvas, then mark it complete to freeze it. Freezing mints **solutions** — the concrete deliverables that realize the proposal. Solution kinds are `hook`, `source_change` (shown as **Customization**), `conduit`, `config`, `native`, `documentation`, `app`, `data_manipulation` and `skill`. Solutions ship through **releases**: every deploy is tracked, audited, monitored against a pre-release baseline, and reversible. Full surface: [Development](/tenant/development/). *** ## The Analyzer [Section titled “The Analyzer”](#the-analyzer) The customization-analysis surface for a connected source. It inventories what an account has been customized into — custom fields, records, lists, scripts, workflows, roles, forms, and saved searches — and sorts the risk it carries into five families: inventory, GL posting, fulfillment, data integrity, and security. Findings don’t stay a static report; they enter the development pipeline as signals and proposals. NetSuite-specific today. Full surface: [Analyzer](/tenant/analyzer/). *** ## Apps [Section titled “Apps”](#apps) Internal apps built on your canonical data and served inside your instance at `/a/`, with an end-user launcher at `/apps`. An app is generated from a plain-English brief through the proposal pipeline — it is one of the solution kinds — and your instance keeps the app’s source of record so it can be refined later. Apps act as the signed-in user, so the same RLS applies to them as to everything else. Full surface: [Build apps](/build-apps/). *** ## Knowledge base [Section titled “Knowledge base”](#knowledge-base) Your instance’s living memory of how the business actually runs — a tree of markdown pages organised process-first, with drafts, immutable published releases, and comments. It is both somewhere your team reads and the grounding Pilot answers “how do we do X” from. Full surface: [Knowledge base](/tenant/knowledge-base/). *** ## Originating system [Section titled “Originating system”](#originating-system) A single column on every canonical row that records *who wrote this most recently* — `source` (the external system) or `hybrid` (Turbobase’s own write path). It’s the linchpin of the realtime listener: only `originating_system='hybrid'` writes enqueue a write-back, so source-driven inbound writes don’t bounce back as outbound writes and create a feedback loop. Enqueuing is itself gated per source: write-back ships **off**, so until it’s enabled for a given source the `hybrid` write lands in your canonical mirror without being pushed upstream. *** ## Glossary [Section titled “Glossary”](#glossary) Every word on this page, and every word you meet elsewhere in Turbobase, is defined once — on the [Glossary](/getting-started/glossary/). That page is the single place the vocabulary lives, so a word cannot mean one thing here and something else there. *** ## Where to read more [Section titled “Where to read more”](#where-to-read-more) * **Architecture diagram** — [`architecture`](/architecture/) * **Build apps on Turbobase** — [`build-apps`](/build-apps/) * **NetSuite onboarding** — [`netsuite-oauth-setup`](/netsuite-oauth-setup/) Questions the docs don’t answer? Email . # Add sources > Bring additional sources into an instance that is already running on Oracle NetSuite. Shipped Your first source is connected during the [setup wizard](/getting-started/connect-your-first-source/), and for most instances that source is Oracle NetSuite. This page covers adding *more* sources to an instance that’s already provisioned and set up. Additional sources are an extension of the same canonical layer, not a separate system: a new source writes the same canonical tables in the same Postgres, under the same row-level security, and [Atlas](/tenant/atlas/) consolidates entities that appear in more than one of them. ## The connect-source flow [Section titled “The connect-source flow”](#the-connect-source-flow) Connectors take one of two console routes, and which one a source uses is a property of the connector, not something you choose. **Shared-app OAuth connectors** — **Jira, GitHub, Google Workspace, Asana, Notion, QuickBooks, Intercom, Ramp, Business Central, Workday, Zoho CRM, and Xero** — connect on the console’s standalone connect-source page: ```text /instances//connect-source/ ``` **Every other source** — **NetSuite, Stripe, HubSpot, Shopify, Zendesk, Salesforce, Bill.com, Fireflies, GetSales, Granola, FeedHive, DocuSeal, PrintNode, WhatsApp Business, and Azure Blob Storage** — connects through the setup wizard’s connect step, re-entered on your running instance: ```text /instances//setup?source=&new=1 ``` That link renders the same connect form your first source used. You don’t normally type either address: the **Add connection** tiles in your app and the **Reconnect** button on a source both open the right one for you. **Connecting a source for the first time and adding a *second* connection of a source you already have are different links.** A first connect is the address above. An additional connection carries an extra flag — `?new=1` on the connect-source route, `&connection=new` on the wizard route — because the two actions must not be confused: see [More than one connection of the same source](#more-than-one-connection-of-the-same-source) below. The flow mirrors the first-source connect: 1. Open the connect page for the source on your instance. 2. For shared-app connectors, click **Connect {Source}** and Turbobase redirects you to the provider’s own consent screen, where you pick the workspace / account / company. 3. The provider redirects back; the console completes the OAuth exchange (write-only into your instance’s secret store) and polls the connection to success. A few connectors collect a little config first. For example, **Business Central** asks for your Entra tenant id and the BC environment before the OAuth redirect; the zero-input connectors render just the connect button. The NetSuite card alone carries the **Advanced settings → Data sync** choice described in [Connect your first source](/getting-started/connect-your-first-source/): leave it on to mirror records, turn it off to run NetSuite on customizations only. On every other connector, mirroring records is the whole connector, so connecting one starts the mirror and there is no switch to find. ## More than one connection of the same source [Section titled “More than one connection of the same source”](#more-than-one-connection-of-the-same-source) You can connect many *different* sources to the same instance. You can also hold **more than one connection of the same source**: two NetSuite accounts, two QuickBooks companies, Stripe sub-accounts. Each is its own connection, with its own mirrored rows kept apart so records with the same internal id in two accounts are never merged into one. Multiple connections of one source are enabled per instance: Turbobase staff turn it on for you, and until they have, a connected source’s tile offers no **Add a connection** affordance. Ask if you need it. Adding a second connection is deliberately a different action from **Reconnect**. Reconnect re-authorises the account you already have; adding a connection brings on a new one. Use the source’s Reconnect button to re-authorise, and **Add a connection** to add. Pointing an existing connection at a different account would silently mix two accounts’ data. ## Salesforce [Section titled “Salesforce”](#salesforce) Salesforce asks a little more of you than most sources, because the app your org signs in through is one **you** create. Read this before you start: the steps are short, but a missing setting shows up as a refused connection rather than as a prompt. **Which editions can connect.** Enterprise, Unlimited, Performance and Developer edition orgs have API access and connect as they are. **Professional and Group edition orgs do not have API access by default** — Salesforce sells it as an add-on, and until it is on your org, a connection attempt is refused and says so. If you are not sure which you have, Salesforce shows it under Setup → Company Information. **Create the app Salesforce now asks for.** In Setup, create a new **External Client App** with Distribution State **Local**, enable OAuth, and give it the callback URL the connect page shows you. Ask for the scopes the page lists (`api` and `refresh_token, offline_access`, plus the identity scope), leave PKCE and “require a secret” set to match what the page asks for, and under the app’s policies choose **All users may self-authorize**, a refresh-token policy of **valid until revoked**, and **relax IP restrictions**. Then copy the consumer key and secret into the connect page — Salesforce asks for a verification code before it shows them to you, and a brand-new app can take a few minutes to start working. If you already have a working **Connected App**, its key and secret still connect. You only need an External Client App because Salesforce stopped allowing new Connected Apps to be created; it has not stopped the ones that exist. **Production or sandbox, and your My Domain.** The connect page asks which you are connecting, and the choice is part of that connection rather than a setting on your instance — so you can hold a production org and a sandbox side by side as two connections. If your org uses a My Domain, give it on the same page (for example `acme.my.salesforce.com`); anything that is not a Salesforce host is refused there and then. **A sandbox needs its own app, every time it is refreshed.** Salesforce does not copy a Local External Client App into a new or refreshed sandbox. So create one in each sandbox you connect, and expect to create it again after every sandbox refresh — a sandbox connection that stops working just after a refresh is almost always this. **Connect as a user who can see what you want mirrored.** Salesforce’s own record-level sharing applies to the connection exactly as it applies to the person who made it, so a user who can only see their own opportunities mirrors only those. A dedicated integration user with **API Enabled** and **View All Data** is the usual choice. You are not stopped from connecting as a narrower user — the connection warns you instead, and your instance’s Health tab goes on naming anything the connection cannot read, so a half-mirrored table is never a mystery. **Your sign-in keeps itself alive.** Salesforce sessions expire after a couple of hours of quiet, and Salesforce withdraws a connection’s permission to sign in again if 30 days pass without it being used. Your instance renews both on its own and shows you the date it last did. If the permission really has been withdrawn — someone revoked the app, the connecting user was deactivated — the Health tab says so in those words and Reconnect is the repair. ## Xero [Section titled “Xero”](#xero) Xero connects as a shared-app OAuth grant on the connect-source page. Clicking **Connect Xero** sends you to Xero’s own consent screen, where you choose **the organisation** you want mirrored. Three things are worth knowing before you connect it: * **One connection holds one Xero organisation.** Your login may administer several; the one you pick on the consent screen is the one this instance mirrors, and choosing a different organisation on a later reconnect is refused rather than silently switched. Re-consenting to the *same* organisation is how you repair a connection Xero has expired. * **Turbobase only ever reads.** It never creates, edits, voids or deletes anything in your Xero organisation. The connection is one-way by design, not by configuration — there is no setting that changes it. * **Contacts, invoices, bills, credit notes, payments, purchase orders, bank transactions, manual journals, your chart of accounts, your items and your cost-tracking categories** are mirrored, and they land in the same tables as everything else you have connected. Your **tracking categories** come across twice over: each line names the option it is tagged with, and the options themselves become rows you can list and count — one row per option, with the category it belongs to on every one of them. An option you have archived in Xero is still there, marked inactive, so an older line that uses it still makes sense. Changes to contacts and invoices arrive within moments; everything else refreshes on a schedule, so allow up to four hours for a new payment or bank transaction to appear. ## GitHub [Section titled “GitHub”](#github) GitHub connects as a shared-app OAuth grant on the connect-source page. There is nothing to type: clicking **Connect GitHub** sends you to GitHub’s own install screen, where you pick the account or organisation and **which repositories** Turbobase may see. Three things are worth knowing before you connect it: * **The repositories you pick are the whole of what is mirrored.** Issues and their comments, pull requests and their reviews, labels, milestones, boards and cards, discussions, workflow runs and the files behind them come in for the repositories on that install screen, and for no others. Narrow or widen the selection on GitHub and the connection follows it. * **Changes arrive as they happen.** GitHub signs the calls it makes to your instance, so an issue opened or a run finished is in your database moments later rather than on a four-hour schedule. * **Turbobase reads until writing is switched on.** Opening an issue, editing one, moving its labels, replying on an issue, a pull request or a discussion, committing a file onto a branch behind a pull request, and starting a workflow that offers a manual run are all built — and all held shut until Turbobase staff turn writing on for your instance. Nothing is ever re-run, cancelled, approved or deleted on your behalf. ## Google Workspace [Section titled “Google Workspace”](#google-workspace) Google Workspace connects as a shared-app OAuth grant on the connect-source page, and **what it brings in is your shared drives**. There is nothing to type: you approve on Google’s own consent screen with an ordinary sign-in. A shared drive belongs to your organisation rather than to a person, so one connect reads the same documents whoever made it. **Gmail, personal My Drive and Calendar are not part of this connector** — reaching those would need a grant over your whole domain, and Turbobase does not ask for one. Once it is connected, the instance’s **Shared drives** screen in the console is where you say which drives to mirror, and it is not an optional setting: a connection with nothing picked reads nothing at all. The screen lists the shared drives the connect found and you tick the ones you want; a drive you have not ticked is never read, and un-ticking one stops it. Documents, spreadsheets, slides and the other files on a ticked drive land alongside your other knowledge sources, with their text read out so the assistant can answer from what they say. If a shared drive was created after you connected, it won’t be on the list yet — the list is what the connect saw. Reconnect the source and the new drive appears for you to tick. New and changed files arrive as they happen — Google calls out to your instance when a drive changes. The connection only ever reads: nothing Turbobase does creates, edits or deletes a file in your Google Workspace. ## PrintNode [Section titled “PrintNode”](#printnode) PrintNode connects with an **API key** rather than an OAuth redirect, and it is the shortest connect in the product: the key is the whole of what you type. Find it in PrintNode under your account’s API keys, then paste it into the PrintNode step of the wizard. Three things are worth knowing before you connect it: * **It is a printing connector, not a records one.** The printers you already have — and the computers they are attached to — are mirrored into your instance so that an automation can name one. Your app lists them on **Data → Synced records**; expand the `printer` row to find a printer’s id. * **Printing is the write, and it starts off.** A print job raised in Turbobase is sent out through PrintNode and paper comes out of your own printer. Because that cannot be undone, sending is a separate per-instance setting Turbobase staff enable on request. Until then the connection only reads. * **A job says how it ended.** PrintNode answers when it has accepted a job rather than when the page is printed, so Turbobase follows the job up and settles it on the row. A job still reading as sent has not printed yet. ## FeedHive [Section titled “FeedHive”](#feedhive) FeedHive connects with an **API key** rather than an OAuth redirect. Find it in FeedHive under **Settings → Account → API Key**, then paste it into the FeedHive step of the wizard. Three things are worth knowing before you connect it: * **Turbobase only reads until publishing is switched on.** Out of the box it never creates, schedules or edits a post in your FeedHive account. Publishing is a separate per-instance setting that Turbobase staff enable on request, so the connection stays one-way until you ask for it to be otherwise. Even with it on, Turbobase never deletes a post. * **New posts appear within about four hours, not instantly.** FeedHive can call out when a post publishes, but it offers no way to prove such a call really came from FeedHive — so Turbobase declines to accept them and refreshes on its own schedule instead. * **Your posts land alongside your other knowledge sources**, not in a table of their own, so the assistant can answer questions about what your company has said publicly, when, and on which channel. A post published to several social accounts at once is stored once, not once per account. ## DocuSeal [Section titled “DocuSeal”](#docuseal) DocuSeal connects with an **API token** rather than an OAuth redirect. Find it in DocuSeal under **Settings → API**, then paste it into the DocuSeal step of the wizard. Four things are worth knowing before you connect it: * **Say which DocuSeal cloud your account is on.** DocuSeal runs two — `docuseal.com` (US) and `docuseal.eu` (EU) — and a token issued in one is not valid in the other. The wizard defaults to the US cloud, which is what you get if you never chose. Picking the wrong one looks exactly like a bad token, so it is worth checking rather than guessing. * **A self-hosted DocuSeal cannot be connected.** Only the two published clouds are accepted. * **Turbobase reads by default, and only reads.** Your signature requests, the people they were sent to and the templates behind them are mirrored into your instance. Sending a request *from* Turbobase is a separate switch that starts off — ask us to turn it on once you have seen the connection working. Nothing leaves your DocuSeal account until you do. * **The webhook secret is optional, and skipping it costs freshness.** If you set one in DocuSeal (**Settings → Webhooks**, pointed at your instance), signatures show up in Turbobase as they happen. Without it, Turbobase refuses deliveries it cannot verify and refreshes on its own schedule instead. You can add it later. ## WhatsApp Business [Section titled “WhatsApp Business”](#whatsapp-business) WhatsApp Business connects by **signing in to Meta** in a popup and choosing the WhatsApp Business account to connect — there is nothing to find and paste. If your business has several accounts, connect each one; they stay separate on your instance, and a phone number in one is never confused with the same number in another. Five things are worth knowing before you connect it: * **Conversations become records, not a screen.** The person you are talking to is a contact, the thread is a conversation, and every message is an activity row beside everything else your instance knows about that person — so a customer’s WhatsApp history sits next to their orders and their invoices. Turbobase does not add an inbox or a chat view, now or later: reading conversations and replying are things an app built on your instance does, over its API. * **Who answers a number decides who can read it.** Each business number can be assigned to a person or a role through your instance’s API, and that assignment is what controls visibility: the person it names reads that number’s conversations, nobody else does, and a number nobody answers is readable by administrators only. Administrators read everything. The assignment is yours alone — it is never sent to Meta. * **Sending starts off, and WhatsApp decides what may be sent.** A reply raised in Turbobase goes out under your own verified business name and cannot be withdrawn, so sending is a separate per-instance setting Turbobase staff enable on request. Once it is on, two of WhatsApp’s own rules apply: you may send ordinary text only within **24 hours** of the customer’s last message, and outside that window only a **template WhatsApp has approved**. Both are checked before anything leaves your instance, so a refused send costs nothing and says what to send instead. * **Meta bills you for messages, not us.** Per-message charges go to your own WhatsApp Business account on the payment method you hold with Meta. They do not come through Turbobase and do not appear on your Turbobase invoice. * **History before the connection does not arrive.** WhatsApp publishes no way to read past messages, so your instance mirrors conversations from the moment the account is connected onward. The same is true of anything sent from the WhatsApp Business phone app on a number you also use there. ## Azure Blob Storage [Section titled “Azure Blob Storage”](#azure-blob-storage) Azure Blob Storage connects with a **Microsoft Entra application** rather than an OAuth redirect. In the Azure portal, register an application under **Microsoft Entra ID → App registrations**, give it a client secret, and grant it the **Storage Blob Data Reader** role on the container you want mirrored — or **Storage Blob Data Contributor** if you also want Turbobase to be able to add files. Then paste the directory (tenant) id, the application (client) id and the client secret into the Azure Blob Storage step of the wizard, along with your storage account name and the container. Five things are worth knowing before you connect it: * **One connection holds one container.** Not one storage account — one container inside it. If you keep documents in two containers, connect each as its own connection; nothing Turbobase does to one can reach the other. * **Choose how the files are kept, and the choice is yours to make.** **Copied** brings each file into your instance, so reading one never depends on Azure being reachable and never costs you egress again. **Left in Azure** keeps only a pointer, so you store nothing twice and pay egress each time somebody opens a file. The wizard asks and does not pick for you, because the right answer depends on your bill rather than on your data. * **Either way the assistant can answer from what your files say.** Text is read out of a file when it is mirrored, whichever mode you chose, so leaving the files in Azure saves you storage without costing you search. Your documents land alongside your other knowledge sources, not in a table of their own. * **Turbobase only reads until you ask for more.** Adding files is a separate per-instance setting that Turbobase staff enable on request, so the connection stays one-way until you ask. When it is on it covers **the whole connected container, at any folder depth** — there is no narrower scope to pick, so connect a container you are content for Turbobase to write into. Removing a file is built but not yet available by any route. * **Writing needs a container Azure can undo.** A write to blob storage is immediate and has no review step, so Turbobase refuses to write at all unless the account has **blob versioning** or **blob soft delete** turned on. It is checked when you connect, and again before anything would be overwritten. If neither is on, the connect is refused and tells you which to enable. New and changed files appear within about four hours rather than instantly: Azure can be made to call out when a blob changes, but that is a subscription you would create and pay for in your own Azure account, so Turbobase refreshes on its own schedule instead. ## Pausing a connection, and removing one [Section titled “Pausing a connection, and removing one”](#pausing-a-connection-and-removing-one) A connection’s life doesn’t end at connecting it. The instance’s **Connections** screen in the console lists every connection you hold, one row each, and carries three actions: **pause** one, which stops it syncing in both directions; **resume** it again; and **remove** it, which deletes the records it brought in. **+ Add a connection** is on the same screen, for a source that holds more than one. **Pausing is the reversible one, and it changes nothing you already have.** A paused connection stops being polled and its webhook deliveries are discarded, so no new records come in — and nothing goes the other way either: a change you make in Turbobase to a record that came from a paused connection is refused, with a message telling you the connection is paused, rather than being accepted and silently never sent. Everything already mirrored into your instance stays exactly as it is, and your apps, your reports and your queries carry on reading it. Resume it whenever you like and it picks up from where the source is then, and changes start flowing back again. Pause acts on **one connection**: if you hold two NetSuite accounts you can pause one and leave the other syncing. Your app shows a paused connection as **Paused** on its [Sources](/tenant/source-health/) row, so a connection that has gone quiet doesn’t read as a broken sync. **Pausing is not the same as turning data sync off.** The [data sync](/getting-started/connect-your-first-source/) choice is made once, per source, at connect time, and it can only be turned on — it decides whether a mirror exists at all, and app surfaces start depending on that mirror the moment it does. Pause is the other switch: per connection, and always reversible. **Removing a connection deletes the records it brought in, permanently.** There is no undo and no backup. Every mirrored row that came from that connection goes, along with the connection itself; a consolidated customer that only that connection knew about goes with it, and one that another connection also knows about stays. The console asks you to type the connection’s name before it will proceed, and offers pause as the non-destructive alternative in the same dialog. Re-connecting the same account afterwards starts a fresh, empty backfill — it does not bring the old rows back. Removing a connection does not revoke your other connections’ access: the stored credentials for a source are only cleared when its **last** connection is removed. ## Per-instance gating [Section titled “Per-instance gating”](#per-instance-gating) Adding a source to a live instance is enabled per instance and per connector: Turbobase staff turn a connector on for your instance. If a source isn’t enabled for you yet, the connect page surfaces a contact path instead of the connect button. Reach out if you need a connector turned on. ## After connecting [Section titled “After connecting”](#after-connecting) A newly connected source starts mirroring into your instance’s database. Watch it sync and confirm health from your app’s [source health](/tenant/source-health/) view, and browse the new data through your [data model](/tenant/data-model/). New sync volume shows up in [Billing and usage](/console/billing-and-usage/). ## Related [Section titled “Related”](#related) * [Connect your first source](/getting-started/connect-your-first-source/): the in-wizard first connect. * [Orgs and instances](/console/orgs-and-instances/): instance status and where the connect entry points live. # Billing and usage > Track usage and manage billing for your Turbobase instances from the console. Shipped The [console](/console/overview/) gives you usage tracking for each instance today, with self-service billing on its way for each [organization](/console/orgs-and-instances/). Billing is scoped to your **active org**: switch orgs in the nav to see another org’s billing. ## Usage [Section titled “Usage”](#usage) Usage is live today. It’s tracked per instance and rolled up per billing period; each instance has a **Usage** view (`/instances//usage`, linked from the instance’s row on the instances list) showing: * **Current period** — usage so far in the open billing period. * **Recent periods** — a history of prior periods. * **Lifetime** — cumulative totals. The metrics Turbobase meters are: * **Sync events** — the volume of records mirrored from your connected sources. * **AI tokens (in / out)** — input and output tokens consumed by Pilot, your AI assistant, and the other AI agents in your app. Inside the app the same usage is broken down by tier (Frontier, Chat, Fast and Other); what’s reported is token counts, not a dollar figure or the underlying AI provider. * **CPU hours**, **egress (GB)**, and **peak database size (GB)** — the infrastructure footprint of your instance. These roll up from the agents running inside each instance, so what you see reflects real consumption — not an estimate. ## Billing — coming soon [Section titled “Billing — coming soon”](#billing--coming-soon) The **Billing** tree (`/billing`) is in the console but sits behind a **“coming soon”** cover while the pricing model is finalized — you won’t be charged anything you haven’t seen in writing. If you need to talk pricing now, reach out to your Turbobase contact. When billing activates, the pages already under the cover open up: * **Billing details** (`/billing/details`) — your customer record (billing email and contact info). * **Payment methods** (`/billing/payment-methods`) — the cards on file; add or update a card. * **Invoices** (`/billing/invoices`) — your invoice history, with per-invoice detail and downloadable copies (and a CSV export of the list). Paid invoices also get a downloadable PDF receipt. * **Add-ons** (`/billing/addons`) — optional capabilities you can layer on top of your plan. Each add-on is priced as a flat monthly charge, metered on usage, or included up to a limit in your plan; it applies per instance or org-wide depending on the add-on, and some require Turbobase staff approval before they activate. Note Relatedly, the plan picker on the create-instance form renders the tiers but is locked while pricing is finalized — every new instance is created on the entry plan, **Ignition**. Usage metering runs as described above regardless. ## Who can see billing [Section titled “Who can see billing”](#who-can-see-billing) Billing is an org-level surface, gated by your console (customer-realm) membership of the org. It governs your subscription only; it never exposes the business data inside an instance, which is gated separately by the app’s own users. See [Console overview](/console/overview/) for the realm split. ## Related [Section titled “Related”](#related) * [Orgs and instances](/console/orgs-and-instances/) — how orgs own the instances you’re billed for. * [Add sources](/console/add-sources/) — connecting more sources drives sync-event usage. # Orgs and instances > How orgs own instances in the console and how to manage them. Shipped Two objects structure everything in the [console](/console/overview/): **organizations** own **instances**. ## Organizations [Section titled “Organizations”](#organizations) An organization (org) is the ownership and billing boundary. It owns instances, holds members, and is where invoices and payment methods live. * **Create** an org at `/orgs/new`. The console suggests a URL-safe slug from the name, and asks for a contact email; a website and a phone number are optional. Your own role is shown but not yours to pick — the first member of a new org is always its admin. * **Switch** orgs from the nav. Your **active org** scopes the create-instance form and the billing views. * **Settings** — an org admin can rename the org from its settings page. Any member can leave an org from the same page — except the last admin, who must promote another member to admin first so the org isn’t left unmanageable. A newly self-signed-up org starts disabled until Turbobase staff enable it. You can still create an instance in the meantime — it keeps your slug claim and parks with a **New (no access)** badge and an **Awaiting approval** note while you wait. Once the org is enabled the badge becomes **Pending**, and an instance admin gets a **Start Provisioning** button on the row — or **Launch instance** on the instance’s provisioning page, under “Your organization is approved”. ### Members and access [Section titled “Members and access”](#members-and-access) Manage who can do what from the org’s **Members & Access** page (admin-only): * **Org roles** — each member is an org **admin** or **viewer**. Admins manage members, invitations, and org settings; viewers are read-only (they can list the org’s instances and open usage, but can’t change anything). * **Per-instance roles** — separately from the org role, each member can hold a role on each instance: **admin** (manage the instance’s config and team, delete it), **developer** (work with the instance’s data, not its config), or **viewer** (read-only). The page lists one row per member; the **Instance access** cell summarises what they hold and expands to a line per instance, each with its own role picker — **No access**, viewer, developer or admin. * **Manage instances** — managing the org is separate from being allowed to spin up (or tear down) production. Creating or deleting an instance needs this org-level permission, a checkbox on the member’s row that an org admin ticks explicitly; being an org admin alone doesn’t confer it. * **Scoped invites** — when inviting a teammate, you pick their org role *and* a per-instance role for each existing instance (defaulting to no access), so the grants land the moment they accept. * **Guards** — the console blocks changes that would lock you out: you can’t suspend or remove the last active org admin, and you can’t untick **Manage instances** on yourself when you’re its last holder. Member and access changes are recorded in the org’s audit log, shown on the same page. ## Instances [Section titled “Instances”](#instances) An instance is one provisioned Turbobase environment — its own dedicated Postgres database and its own app at `.turbobase.app`. Each instance belongs to exactly one org. * **Create** at `/instances/new`, scoped to your active org. Pick a name; the slug becomes your subdomain. Instances are hosted in our US East (Ashburn) region — the single location on offer today, so there’s no region picker. The plan selector shows the tiers, but it’s locked while pricing is finalized: every new instance is created on the entry plan, **Ignition**. * **List** at `/instances`, grouped by org. Each row shows the instance’s live status and the one action that state allows while it’s still being set up: **Start Provisioning** (approved and waiting on you), **Resume** (provisioning already under way), **Set-up** (run the wizard) or **View failure**. * The instance’s slug is the link that opens your Turbobase app, in a new tab. It only becomes a link once setup is finalized; before that it’s plain text and the row points you back into the [setup wizard](/getting-started/connect-your-first-source/). * **Connections** on a finalized row opens that instance’s connections screen. Every system you’ve connected has a row there, and you can pause one — which stops it syncing in both directions until you resume it — or remove it, which permanently deletes the records it brought in. [Add sources](/console/add-sources/) covers both in full. * **Usage** and **Delete** are icon buttons rather than labelled ones — Delete is the trash glyph. Hover either one to see its name. * **Delete** is self-service but deliberately guarded: you must hold the **admin** role on that instance *and* **Manage instances** on the org, and you confirm by typing the instance’s slug exactly into the confirmation modal. Teardown then runs asynchronously — the instance shows **Deleting…** until it’s gone. ## Provisioning status [Section titled “Provisioning status”](#provisioning-status) Instance status moves through a small set of stages. The console renders each one as a friendly label and color (green = ready, amber = in-flight, red = needs attention, gray = neutral). The states you may see: | Console label | Meaning | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | New (no access) | Created against a not-yet-enabled org; parked with an **Awaiting approval** note until staff enable it | | Pending | Your org is enabled and the instance is yours to start — **Start Provisioning** on the row, or **Launch instance** on its provisioning page | | Provisioning… | Work has started | | Provisioning… (database) | Building your dedicated database schema | | Provisioning… (services) | Deploying the instance’s app and sync services | | Provisioning… (waiting for health checks) | Waiting for everything to report healthy | | **Ready** | Live; ready for setup / use | | Paused | Suspended | | Failed | Provisioning failed — contact support | | Upgrading… (with a database / services qualifier) | A version upgrade is in flight | | Upgrade failed | An upgrade didn’t complete — contact support | | Deleting… | Teardown in progress | | Deleted | Terminal — the instance is gone | The happy path runs Provisioning… → database → services → health checks → **Ready**. From Ready an instance can later move into an upgrade, into Paused, or into Deleting → Deleted. A failure during provisioning shows **Failed**; a failure during an upgrade shows **Upgrade failed**. Reaching **Ready** doesn’t mean setup is done — a Ready instance still needs the [setup wizard](/getting-started/connect-your-first-source/) run before its app opens. That’s why a Ready row keeps its **Set-up** button until the wizard is finalized, and only then does its slug become a link. ## Related [Section titled “Related”](#related) * [Provision your instance](/getting-started/provision-your-instance/) — the step-by-step create flow. * [Add sources](/console/add-sources/) — connect more systems to a live instance. * [Billing and usage](/console/billing-and-usage/) — what each org is consuming and owes. # Console overview > Tour of the user console: orgs, instances, billing, and adding sources. Shipped The **user console** at `console.turbobase.io` is your self-service home for everything around your Turbobase subscription. It’s where you sign up, create organizations, provision and manage instances, connect sources, and handle billing — without ever installing or running anything yourself. The console is distinct from your Turbobase app (`.turbobase.app`); see [Open your Turbobase app](/getting-started/open-your-tenant/) for the split. ## What the console offers [Section titled “What the console offers”](#what-the-console-offers) * **Organizations.** The billing and ownership boundary. Create orgs, manage members and their capabilities, switch between orgs. See [Orgs and instances](/console/orgs-and-instances/). * **Instances.** Provision new instances, watch them move through the provisioning states to **Ready**, and open the app once setup finalizes. See [Orgs and instances](/console/orgs-and-instances/). * **Sources.** Connect your system of record during the setup wizard (Oracle NetSuite for most instances), and add more sources to an already-provisioned instance later. See [Add sources](/console/add-sources/). * **Billing and usage.** See per-period usage (sync events, AI tokens, infrastructure footprint) per instance; billing self-service is coming soon. See [Billing and usage](/console/billing-and-usage/). * **Account.** Your console profile, sign-in, and security settings. ## The customer realm [Section titled “The customer realm”](#the-customer-realm) The console is the **customer** identity realm of Turbobase. It has its own sign-in, its own session, and its own user records — entirely separate from: * your **Turbobase app** users (`.turbobase.app`), who sign in with credentials you set during setup, and * Turbobase staff tooling, which you never see. A console account governs *which orgs and instances you can manage and pay for*. It never grants access to the business data inside an instance — that’s gated by the app’s own users and permissions. Sign in to the console to manage your subscription; sign in to the app to work with your data. ## Account security [Section titled “Account security”](#account-security) Your console account’s security settings live at `/account`: * **Change password** — update your password (you’ll confirm your current one). * **Passkeys** — enroll a passkey for phishing-resistant sign-in, and remove it later if needed. * **Authenticator app (TOTP)** — enroll a time-based one-time-password app as a second factor, and remove it later if needed. When a second factor is enrolled, sign-in adds an MFA challenge step — you’ll verify with your passkey or authenticator code after your password. Forgotten passwords are handled by the reset-password flow on the sign-in page. ## Getting started [Section titled “Getting started”](#getting-started) Signing up needs an early-access invite. If you don’t have one, request access at `console.turbobase.io/early-access` — tell us your company, where you are, and roughly how many people you are — and we’ll send an invite link when we’re ready for you. An invite link takes you straight to sign-up with the code already filled in. Once you’re in, start with [What is Turbobase?](/getting-started/what-is-turbobase/) and then [Provision your instance](/getting-started/provision-your-instance/). # Calling the model > Send a prompt to the AI model your instance is already configured with — from an app, from a program, or from inside a process step — and the limits that bound what it costs. Shipped Your instance already has an AI model configured and paid for. This page is how your own code asks it a question. There are two ways in, and they are the same model and the same allowance: * **`POST /v1/ai/complete`** — one prompt in, one answer out. Called from an app’s own screen under the session the person is already signed in with, or from a program with an access token. * **an `ai` step in a process** — the engine makes the call for you, mid-chain, and hands the answer to the next step. See [Writing processes](/extending/writing-processes/). A step’s own `build` function still **cannot** reach the model, and that is deliberate: an extension is pure — no secrets, no network — so the call is made by the engine around it rather than from inside the sandbox. ## `POST /v1/ai/complete` [Section titled “POST /v1/ai/complete”](#post-v1aicomplete) It is a **passthrough**. No skills, no knowledge-base grounding and no system prompt of ours is added to what you send — the prompt that reaches the model is the prompt you wrote. ```sh curl -X POST https://acme.turbobase.app/v1/ai/complete \ -H 'authorization: Bearer tb_pat_…' \ -H 'content-type: application/json' \ -d '{ "app": "reorder-helper", "prompt": "Summarise this purchase order in one sentence: …", "tier": "fast", "maxTokens": 500 }' ``` ```json { "text": "A 240-unit restock of three SKUs from Globex, due 14 October.", "model": "…", "tier": "fast", "usage": { "inputTokens": 212, "outputTokens": 19 } } ``` ### The fields [Section titled “The fields”](#the-fields) | Field | Required | What it does | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `app` | **yes** | The slug of the app spending this call. The allowance is per app and the usage row is keyed on it, so a call that names no app is one nobody can attribute, bound or bill. It must be an app deployed on your instance; a preview’s slug spends its own app’s allowance. | | `prompt` | **yes** | What you are asking. Non-empty, and at most 100,000 characters. | | `tier` | no | Which class of model to use. Defaults to `fast`; your instance decides which tiers are allowed. | | `maxTokens` | no | The most the answer may be. Defaults to 1,024 and is capped by your instance’s per-call limit. | There is **no `model` field**, and sending one does nothing. A caller naming a raw model id picks the instance’s bill; the tier is the knob that keeps that decision the instance’s. ### From an app, use the client rather than the route [Section titled “From an app, use the client rather than the route”](#from-an-app-use-the-client-rather-than-the-route) `src/lib/turbobase.ts` — the file `turbobase apps init` writes into every app project — carries `askModel`, which fills in your app’s slug and turns a limit refusal into a typed error: ```ts import { askModel, TurbobaseAiLimitError } from './lib/turbobase'; try { const { text } = await askModel({ prompt: 'Summarise this order: …', tier: 'fast' }); } catch (err) { if (err instanceof TurbobaseAiLimitError) { // `err.retryAfterMs` is null when waiting would not help — a prompt over // the per-call ceiling, or a tier this instance does not allow. } } ``` An app project scaffolded before this release does not have it; re-copy the file, or call the route directly and send `app` yourself. ### Who may call it [Section titled “Who may call it”](#who-may-call-it) **From an app’s own screen**, the session cookie the person is already signed in with. Nothing extra to arrange — it is that app’s user asking, under the allowance the instance set for that app. **From a program**, a personal access token carrying **Ask this instance’s AI model** (`ai:invoke`). Tick it when you mint the token, on the **Access tokens** page — your account menu, or `/settings/tokens` directly. A token belongs to a Turbobase account, so that page is not offered to administrators who opened the app from inside NetSuite. That permission is **not** on any token by default, including every token that already exists — nothing gains the ability to spend your model budget by upgrading. It is revocable on its own, without touching what else the token does, and it reaches no rows: a token carrying it and nothing else can neither read nor change your data. A token without it is refused `403`, and the model is not called. ## The limits, and what they answer [Section titled “The limits, and what they answer”](#the-limits-and-what-they-answer) Every call bills model tokens against your instance, so four ceilings bound it. An administrator sets them; these are the shipped defaults: | Limit | Default | What it stops | | ------------------- | -------------- | ----------------------------------------------------------------- | | Tokens per minute | 60,000 | A loop spending a day’s allowance in a minute. | | Max tokens per call | 8,000 | One prompt taking most of a minute’s allowance. | | Tokens per day | 1,000,000 | A steady leak nobody notices. | | Allowed tiers | `fast`, `chat` | An app reaching for a model class this instance does not pay for. | These apply to **each app**. Every call must also fit one window the **whole instance** shares — four times the per-minute and per-day numbers above — so the total stays bounded however many apps are calling at once. The limits are checked **before** the model is asked, so a refused call costs nothing. A call that goes through spends what it actually spent, not what it estimated. ### The refusals [Section titled “The refusals”](#the-refusals) | Status | `error` | What happened | | ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `429` | `ai_token_limit` | A per-minute or per-day ceiling. The body carries `retryAfterMs` — **when it clears** — and a `retry-after` header beside it, so you wait rather than poll. `scope` says whether it was your app’s own window (`app`) or the one every app shares (`instance`). | | `404` | `ai_app_not_found` | `app` is not an app deployed on this instance. | | `403` | `view_as_session` | The call came from a view-as session, which is read-only. | | `400` | `ai_tier_not_allowed` | You asked for a tier this instance does not allow. Waiting never clears this; ask an administrator. | | `503` | `ai_limits_unreadable` | The limits could not be read. **Fails closed** — the call is refused rather than let through unbounded. | | `503` | `llm_unavailable` | No model is configured on this instance. | | `503` | `ai_budget_paused` | The instance’s spend gate has paused model calls. The body carries `until`. | | `403` | `insufficient_scope` | The token does not carry `ai:invoke`. | `retryAfterMs` matters more than it looks: without it the only recovery from a rate limit is to poll, which spends the allowance you are waiting for. ## Declaring your app’s own, lower limits [Section titled “Declaring your app’s own, lower limits”](#declaring-your-apps-own-lower-limits) The instance’s limits bound the **bill**. Your app’s own limits bound **your app** — so that a runaway loop in one app exhausts its share rather than everybody’s. Declare them in `public/turbobase.json`: ```json { "name": "Reorder helper", "ai": { "tokensPerMinute": 5000, "maxTokensPerCall": 2000, "tokensPerDay": 50000, "tiers": ["fast"] } } ``` Every field is optional, and each is a **narrowing**: declare less than the instance allows and the lower number is what is enforced for your app. Declare **more** and `turbobase ext deploy` / `turbobase apps deploy` refuses the deploy, naming the field and both numbers: ```plaintext this app declares ai.tokensPerMinute of 90000, and this instance allows 60000. ``` The refusal is at deploy rather than at run time on purpose: a declaration above the instance’s limit means an author believes their app may spend more than it can, and the first symptom would otherwise be an unexpected refusal in code they thought they had sized. A deploy is the moment somebody is watching. ## What every call records [Section titled “What every call records”](#what-every-call-records) One `llm_usage` row per call, under `app:`, with the input and output token counts, the provider, the model and who asked. That is what the instance’s own spend reporting reads, and it is why `app` is required rather than inferred. A call made by a process’s `ai` step is recorded the same way, under `process:`, and also lands on that run’s ledger with its token counts — so a re-delivered run hands on the answer it already paid for instead of billing a second one. # Deploy, plan, promote > Ship extensions with config-as-code — export a bundle, plan the diff, deploy, and promote across environments behind a fail-closed gate. Shipped Once an extension passes [its tests](/extending/sandboxes-and-testing/), you ship it. Turbobase supports two deploy styles: a quick **single-file** deploy for one extension, and **config-as-code** for the whole instance — where **your repository is the desired state**, `plan` diffs it against an instance, and `deploy --to` applies it. `turbobase logs` closes the loop after a deploy. ## Single-file deploy [Section titled “Single-file deploy”](#single-file-deploy) The fast path — push one authored extension straight to the instance: ```sh turbobase ext deploy hooks/customer.before_save.ts # deployed ns:customer:require-name → status=active (created). ``` The CLI parses the file’s metadata (id / recordType / event / source / kind), `POST`s it to `/v1/extensions`, and prints the resulting id, status, and outcome. A non-admin personal access token (PAT) gets a `deploy forbidden (403)`. ## Config-as-code — your repository is the desired state [Section titled “Config-as-code — your repository is the desired state”](#config-as-code--your-repository-is-the-desired-state) For everything else, the unit of deploy is **your project tree**. These four inputs are the config-as-code source of truth for an instance’s deployable surfaces, and `plan`, `deploy --to` and `promote` all build from them: | In your repo | Becomes | | ------------------------------------ | --------------------------------------------------------------------- | | `hooks/**/*.ts` (`defineHook`) | hooks — including nested folders, which is what `ext new hook` writes | | `conduits/**/*.ts` (`defineConduit`) | conduits | | `turbobase/sync.json` | promoted-field ownership + mirrored tables | | `turbobase/schedules.json` | scheduled jobs | `turbobase apps init` scaffolds all four, so a project has them from the first commit. Nothing has to be generated first — a plan reads the branch you are on, which is what lets a pull request show what merging would change. ### Adopting an instance that already has config [Section titled “Adopting an instance that already has config”](#adopting-an-instance-that-already-has-config) If your instance was configured before the repo existed — hooks deployed one file at a time, a schedule set up in the console — pull it down first: ```sh turbobase ext export # wrote turbobase/bundle.json (142 lines). ``` `ext export` calls `GET /v1/config/export` (needs `extensions:deploy`; a PAT without it gets a clear 403). This is the **adopt** path, not the authoring one: move the extensions it lists into `hooks/` and `conduits/`, and the file stops being consulted. A project that authors nothing in-tree still falls back to `turbobase/bundle.json`, so nothing breaks while you migrate. ## `plan` — diff before you write [Section titled “plan — diff before you write”](#plan--diff-before-you-write) `plan` prints a terraform-style diff of **this project** against a target env’s **live** config. It writes **nothing** — run it on every pull request: ```sh turbobase ext plan --to prod # plan against prod: # + hook ns:customer:require-name # ~ conduit shop2ns:order # - hook custom:legacy:foo # # 1 to add, 1 to change, 1 to destroy. ``` `--from ` is advisory (it just labels which env the config was authored against); your project is always the desired state and `--to` selects the env whose live state you diff against. An empty plan prints `(no changes — up to date.)`. A `-` line means the instance has something your repo does not declare. Reading those **before** merging is the point of planning on a pull request — but note that `deploy` will not act on them unless you ask (see below). ## `deploy --to` — apply the whole bundle [Section titled “deploy --to — apply the whole bundle”](#deploy---to--apply-the-whole-bundle) To apply the bundle (idempotently) to an env: ```sh turbobase ext deploy --to sandbox # applied bundle to sandbox: +1 ~1 -1 (2 backfill(s) queued) ``` `deploy --to` builds the manifest from your project tree and `POST`s it to `/v1/config/apply`, reporting adds / changes and any backfills queued. `` is ignored when `--to` is given. As with single-file deploy, a non-admin PAT gets a 403. ### Removal is opt-in [Section titled “Removal is opt-in”](#removal-is-opt-in) **`deploy --to` adds and updates. It does not remove.** Deleting a hook from your repo does not delete it from the instance; the run prints what it declined to remove: ```sh turbobase ext deploy --to prod # applied bundle to prod: +1 ~1 -0 # 2 resource(s) exist on prod but are not declared by this project — NOT removed: # hook custom:legacy:foo # schedule nightly-legacy-export # Add them to this repo (`turbobase ext export` pulls them down), or re-run with --prune to remove them. ``` Pass `--prune` to take them: ```sh turbobase ext deploy --to prod --prune # applied bundle to prod: +1 ~1 -2 ``` The safe default exists because a repo does not always declare everything already running on an instance. Without it, the first `deploy --to` from a newly scaffolded project — which declares one example hook — would delete every other hook, conduit, promoted field, mirrored table and scheduled job on that instance. Once your repo IS the whole truth for your config, add `--prune` to your CI step. `promote` takes `--prune` too, with the same default. #### A prune never leaves a schedule running a process you removed [Section titled “A prune never leaves a schedule running a process you removed”](#a-prune-never-leaves-a-schedule-running-a-process-you-removed) One removal is refused rather than taken: dropping a **process** while a recurring job on the instance still runs it. The job cannot do anything useful once the process is gone — it fires on its schedule, fails every time, and switches itself off after five failures — so the deploy stops instead: ```sh turbobase ext deploy --to prod --prune # turbobase: bundle apply failed: POST /v1/config/apply → 400: invalid_bundle: # schedule 'rollup-tick' runs the process 'custom:process:nightly-rollup', which # this deploy would remove — the schedule would keep firing, fail every time and # switch itself off after five failures. Keep the process in the bundle, point # the schedule at another process in the same deploy, or drop the schedule in # the same deploy (delete it on the instance if it is not the bundle's) ``` That whole sentence reaches your terminal, ways out included — the refusal is the instance’s own words and the CLI no longer shortens one. Nothing is written when it refuses — not the additions earlier in the same plan. Three ways out, and the right one depends on what you meant: * **Retire both.** Delete the schedule from `turbobase/schedules.json` in the same commit as the process. One deploy, both gone — this is the supported way. * **Move the job.** Point the schedule at a different process in the same commit. The job is screened against the body it will have once the deploy lands, so repointing it at a process you keep — or one this same bundle brings — applies normally, and so does turning it into a chat-prompt or system job. * **Keep the process.** Leave it declared and the prune carries on with everything else. A job somebody created in the app rather than in your repo is not yours to drop from the bundle; delete it on the Scheduled tasks page and re-run the deploy. A process no job runs prunes exactly as before, and so does one whose job was already dead before this deploy: the refusal is about an orphan your deploy would *create*, never one it inherited. ## `promote` — env→env behind a fail-closed gate [Section titled “promote — env→env behind a fail-closed gate”](#promote--envenv-behind-a-fail-closed-gate) Promotion moves a vetted bundle from one env into another — typically `sandbox → prod`. It is guarded by a **fail-closed confirm-slug** check: ```sh turbobase ext promote --from sandbox --to prod --confirm acme # promoted sandbox → prod (acme): +3 ~2 -0 ``` If `--confirm` does **not** exactly match the target instance’s slug, the CLI rejects **before any network write** — nothing is POSTed: ```sh turbobase ext promote --from sandbox --to prod --confirm wrongslug # turbobase: promote refused (fail-closed): … ``` This is the customer promoting their **own** instance config across their own environments. It is unrelated to — and never touches — the control-plane’s production cloud deploys. ## Close the loop — `turbobase logs` [Section titled “Close the loop — turbobase logs”](#close-the-loop--turbobase-logs) After a deploy, watch the extension run: ```sh turbobase logs --subsystem hooks --since 10m # every hook outcome turbobase logs --extension ext_abc123 # this extension's log buffer turbobase logs --conduit shop2ns:order --follow # a CONDUIT's run ledger ``` With no target flag, `logs` reads the unified platform event log — every hook rejection and error, every guardrail verdict, every conduit run, in one stream with one correlation id. `--extension ` reads that extension’s bounded log ring buffer (`[level] ts message` per line) and `--conduit ` streams the `conduit_event` run ledger, polling every `--interval-ms` (default 2000). These two flags replace `turbobase ext logs`, which is removed. ## The full workflow [Section titled “The full workflow”](#the-full-workflow) ```sh turbobase ext export # 1. snapshot live config # edit hooks/ + conduits/, then: turbobase ext lint hooks/foo.ts # 2. lint offline turbobase ext test hooks/foo.ts # 3. dry-run in the sandbox turbobase ext plan --to sandbox # 4. preview the diff turbobase ext deploy --to sandbox # 5. apply to sandbox turbobase ext promote --from sandbox --to prod --confirm acme # 6. promote turbobase logs --extension ext_abc123 # 7. verify it runs ``` ## Next steps [Section titled “Next steps”](#next-steps) * [Sandboxes and testing](/extending/sandboxes-and-testing/) — the steps before deploy. * [Marketplace](/extending/marketplace/) — install / publish instead of authoring locally. * [CLI reference](/cli/reference/#ext-deploy) — every flag. # Marketplace > Install published extensions into your instance and publish your own to the Turbobase marketplace. Shipped Not every extension is authored from scratch. The **marketplace** lets you install a published hook or conduit into your instance with one command, and — if your instance is an approved publisher — publish your own for others to install. Installing and publishing are CLI-only today: there is no in-product marketplace to browse. You install an extension by name with `turbobase ext install`. ## Before you start [Section titled “Before you start”](#before-you-start) Both commands run against the instance you’re [signed in](/cli/overview/#authenticate--turbobase-auth-login) to — the install lands in that instance’s store. Publishing is gated separately: only approved publishers can push an extension to the registry. ### The registry credential [Section titled “The registry credential”](#the-registry-credential) The marketplace is the one part of the CLI that does **not** run on your stored PAT. It talks to the Turbobase registry rather than to your instance, so it takes its own credential — two environment variables, and you need both: ```sh export TURBOBASE_REGISTRY_URL=… # the registry endpoint, given to you with the token export TURBOBASE_REGISTRY_TOKEN=… # ask Turbobase support to issue one ``` **Ask Turbobase support to issue a registry token for your instance.** They give you both values together. The token is shown exactly once when it is created — store it in your secret manager, not in a repo. If you lose it, ask for a new one; issuing a replacement retires the old one. Three things worth knowing about it: * **It is not one of your instance’s internal credentials.** It authorises the marketplace routes and nothing else — it cannot read or write your instance’s data, and it is not the credential your instance uses internally. * **It can be revoked on its own.** If it leaks, ask support to revoke it. Your instance keeps running normally; nothing else is affected. * **Both variables must come from the same place.** The CLI will not pair a URL you set with a credential it found somewhere else in your environment, and `TURBOBASE_REGISTRY_URL` must be `https://` — the token travels to it as an `Authorization` header, so it is never sent over a plaintext connection. With either variable missing, both commands stop before making a request: ```plaintext turbobase: marketplace not configured — set TURBOBASE_REGISTRY_URL and TURBOBASE_REGISTRY_TOKEN. ``` ## `ext install` — install a published extension [Section titled “ext install — install a published extension”](#ext-install--install-a-published-extension) ```sh turbobase ext install acme-recipes # latest version turbobase ext install acme-recipes@1.2.0 # pinned version # installed acme-recipes@1.2.0 → ext_xyz (status=active, created). ``` The CLI fetches the published bundle from the marketplace, parses its metadata, and deploys it — an install lands **active**, with no proposal to approve. On the Extensions tab it then reads as **CLI deploy**, the same origin a hook you deployed yourself carries. A non-admin personal access token (PAT) gets an `install forbidden (403)`. ### Binding a connection at install [Section titled “Binding a connection at install”](#binding-a-connection-at-install) A published bundle is **connection-agnostic**: it never bakes in a specific connection. If the manifest declares a `{ type:'connection' }` input, you bind one of *your* instance’s connections at install time: ```sh turbobase ext install acme-recipes --connection conn_123 # installed acme-recipes@1.2.0 → ext_xyz (status=active, created) bound to connection conn_123. ``` Omit `--connection` for such an extension and the CLI tells you which source the extension wants and refuses until you bind one. The runtime then acts only on that connection. ## `ext publish` — publish to the marketplace [Section titled “ext publish — publish to the marketplace”](#ext-publish--publish-to-the-marketplace) ```sh turbobase ext publish hooks/recipe.ts \ --name acme-recipes \ --pkg-version 1.0.0 \ --manifest manifest.json # published acme-recipes@1.0.0 (kind=hook) to the marketplace. ``` The CLI derives the kind (hook vs conduit, exactly as `deploy` does), validates the optional manifest locally, and publishes. Flags: | Flag | Meaning | | ------------------------- | ------------------------------------------------------------------------------------------------- | | `--name ` | **Required.** Marketplace package name (lowercase, e.g. `acme-recipes`). | | `--pkg-version ` | **Required.** Semver-ish (e.g. `1.0.0`). Not `--version` — that is the CLI’s own version flag. | | `--manifest ` | Optional JSON manifest declaring `inputs[]` (including `{ type:'connection' }`) and capabilities. | ### The publisher allowlist [Section titled “The publisher allowlist”](#the-publisher-allowlist) Publishing is gated by an **admin-managed publisher allowlist**. An instance whose slug isn’t on the list gets: ```plaintext turbobase: publish forbidden (403) — this instance is not an approved publisher. Ask staff to add this slug to the publisher allowlist. ``` Re-publishing an existing `name@version` returns 409 (`bump the version`). ### The connection-agnostic contract [Section titled “The connection-agnostic contract”](#the-connection-agnostic-contract) A published bundle must **not** bake in a literal `connection_id` — that’s validated locally *before* the bundle hits the wire. Instead, a manifest declares a `{ type:'connection' }` input, and the installing instance binds its own connection at install time (above). This keeps a published extension portable across every instance that installs it. ## Install vs. author [Section titled “Install vs. author”](#install-vs-author) | | Install | Author | | ---------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------- | | Source | A published marketplace bundle | Your own `hooks/` / `conduits/` | | Command | `turbobase ext install` | [`turbobase ext deploy`](/extending/deploy-plan-promote/) | | Lands as | Active, straight away | Active, straight away | | Origin on the Extensions tab | **CLI deploy** — an install is not badged apart from a deploy | **CLI deploy**, or **Code baseline** for one your instance ships with | | Connection | Bound at install via `--connection` | Set in your own config | ## Next steps [Section titled “Next steps”](#next-steps) * [Writing hooks](/extending/writing-hooks/) / [Writing conduits](/extending/writing-conduits/) — author what you publish. * [Deploy, plan, promote](/extending/deploy-plan-promote/) — ship a self-authored extension instead. * [CLI reference](/cli/reference/#ext-install) — `ext install` / `ext publish` flags. # Migrating between systems > Move data one connected system has already mirrored into a second connected system — read it, reshape it, and have the target create it — with a process and the write boundary that already ship. Shipped A **migration** here is a shape, not a separate product: rows one connected system has already mirrored into your instance are read, reshaped, and written so that a *second* connected system creates them. A customer arriving with years of Xero history and a brand-new NetSuite account wants exactly that, and every piece it needs already ships — a [process](/extending/writing-processes/) to declare the work, `ctx.query` to read the mirror, and the write boundary to create the result and push it upstream. There is no bulk import endpoint and no migration screen. This page is the shape that works today, the three limits it runs into, and the records it cannot move at all — so you learn them here rather than against a customer’s data. ## The shape [Section titled “The shape”](#the-shape) One process, **one invocation per source row**, and the record naming the system it belongs to: ```ts import { defineProcess } from '@turbobase/extensions'; // The type parameter is what gives `ctx.input` its shape; the `input` schema // below is what the invoke route validates the body against. export default defineProcess<{ externalId: string }>({ id: 'acme:migrate-customer', input: { type: 'object', properties: { externalId: { type: 'string' } }, required: ['externalId'], }, steps: [ { id: 'customer', recordType: 'customer', build: async (ctx) => { // `ctx.query` takes a query STRING, so anything you interpolate into a // filter has to be encoded — an unescaped `&` or `,` in a value is read // as more query, and silently widens the read. const id = encodeURIComponent(ctx.input.externalId); const [row] = (await ctx.query( `entity?select=company_name,email,external_id&entity_type=eq.customer` + `&source_system=eq.xero&external_id=eq.${id}`, )) as { company_name: string; email: string | null; external_id: string }[]; if (!row) throw new Error(`nothing mirrored for ${ctx.input.externalId}`); return { parent: { company_name: row.company_name, email: row.email, // The record names the system it belongs to. source_system: 'netsuite', raw: { migrated_from: { source_system: 'xero', external_id: row.external_id } }, }, }; }, }, ], }); ``` Deploy it like any other extension, then ask for it once per row you are moving: ```sh turbobase ext deploy processes/migrate-customer.ts ``` ```ts // POST /v1/processes/:id — 202 { runId, processId, state: 'queued' } await fetch('/v1/processes/acme:migrate-customer', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ externalId: 'XERO-C-1' }), }); ``` ## The record names its target, not your session [Section titled “The record names its target, not your session”](#the-record-names-its-target-not-your-session) On a **create**, `parent.source_system` names which connected system the new record belongs to, and it is the value the row is stamped with. That is what makes a migration possible at all from a session signed in against the system you are migrating *away from*: the write routes by the record’s own hint, never by the session’s claim. Invoked under a Xero session, the process above still creates a NetSuite record, and the write trail queues it for the NetSuite adapter. Two things to know about the field: * **Naming a system that is not connected is refused** — `422` with `SOURCE_NOT_CONNECTED` — rather than accepted and left with nowhere to sync. * **On an update it is verified, not written.** A record already belongs to a system; restating it is fine, a different value is `422 SOURCE_MISMATCH` — or, on a record type that means a different record in different systems (`account` is a customer in Zoho CRM and Salesforce and a ledger account everywhere else), `404 row not found or not permitted`, because on those the field is also what chose the table the row was looked for in. Either way you cannot hand an existing record to another system by relabelling it. A migration creates; it never re-points. * **On a custom table it is verified, not written — on a create too.** A table mirrored from one system, or authored on the instance, already says which system owns its rows, so a create addressed by its slug or by the `customrecord_`-prefixed spelling of it takes that answer and a disagreeing `source_system` is `422 SOURCE_MISMATCH`. Those tables are per-install and are not what a migration moves; the record types above are. On an instance with one system connected the field can be left off and defaults. Name it anyway in a migration — the whole point is that there are two. ## One invocation per source row [Section titled “One invocation per source row”](#one-invocation-per-source-row) A process declares its `steps` once and the list is **fixed** when the module is deployed — what varies is how many times the platform runs it. The plain shape below is one invocation per source row, driven by whatever is doing the migrating: your app under a signed-in session, a `{ kind: 'process' }` schedule, or a script outside the browser — `turbobase processes invoke`, or a call with a personal access token carrying `extensions:deploy` whose owner is an administrator; the run writes as that owner. See [Keeping a long run going](/extending/writing-processes/#keeping-a-long-run-going). Two declarations change that, and both are the right answer more often than fanning out from a caller: * **`eachRow`** makes the process a migration: one invocation runs the whole step list once per outstanding source row, a slice at a time, queues its own next slice, and each step reads its row from `ctx.row`. See [A migration recipe](/extending/writing-processes/#a-migration-recipe) for the create-then-mark-the-row shape, and [Moving many records](/extending/writing-processes/#moving-many-records). * **`forEach`** repeats a GROUP of steps once per element of an array on the invoked input — for a chain whose length the caller decides, up to the instance’s expansion cap. See [Repeating a group of steps](/extending/writing-processes/#repeating-a-group-of-steps). Three consequences worth planning for: * **Each run is its own unit.** One failing invocation does not stop the others. Each carries its own ledger — `GET /v1/processes/runs/:runId` — with its own steps and its own refusals. * **Idempotency is per run for a chain, and per SOURCE ROW for a migration.** A run redelivered to a worker resumes where it stopped and creates nothing twice. Re-*invoking* a plain chain with identical input mints a new run, and that run creates a **second** record — nothing knows the two invocations meant the same Xero customer, so guard it yourself: stamp provenance on the record, as the example above does, and look for it in `build` before returning a payload. A process that declares `eachRow` needs none of that: its write key is derived from the row’s own `key`, so re-offering a row is a no-op. * **It will not go faster than the source.** Writes of one record type reach a source strictly one at a time, in order, and outbound calls per source are gated. Ten thousand invocations enqueued at once queue. ## The three limits [Section titled “The three limits”](#the-three-limits) | What | Today | Constant | | ------------------------------------------------------------------------- | --------- | -------------------------------- | | Rows one `POST /v1/batch` sub-query returns (not `ctx.query` — see below) | 1,000 | `READ_MAX_ROWS` | | Bytes one `ctx.query` returns | 12 MB | `MAX_BATCH_RESPONSE_BYTES` | | How long a step waits for the source | 5 minutes | `DEFAULT_AWAIT_SOURCE_BUDGET_MS` | The last column is there so this page can be held to it: a test fails the build if a number here stops matching the platform, rather than leaving you to find out from a run. **`ctx.query` hands back the whole result, or throws.** Unlike a browser’s `POST /v1/batch` read, it has no row cap: a step reads in order to decide what to write, and a silently shortened answer would migrate the first thousand records and report success. What bounds it is the byte ceiling above — a read over it fails the step with the limit named. Read a page explicitly (`limit` and `offset`) when a page is what you want, or let `eachRow` take the slice for you, as the example above does. **`awaitSource` waits on a wall clock, and in bulk it will run out.** Declare it on a step only when a *later step in the same run* needs the id the source minted for an earlier one — the ordering it buys is paid for by holding the run open. Behind a queue of other writes of the same record type, five minutes is not a generous budget; it is the ordinary case. **A wait that runs out is not a failure**: nothing was refused, the write is on the trail, and the run ends `committed` with the steps it never reached in `outstanding` and its `reason` naming the step still waiting. The record that step created **is still there**, still on its way to the source. For a bulk migration, leave `awaitSource` off: let each record go, and watch [source health](/tenant/source-health/) for what the source said. ## What cannot be migrated at all [Section titled “What cannot be migrated at all”](#what-cannot-be-migrated-at-all) A step naming a record type that is **read-only** for the target system is refused at the write boundary before anything is created. The run ends `failed`, and the step’s ledger row carries `WRITE_REFUSED` with the message `record type "subsidiary" is not writable` — and no field, because the refusal is about the type rather than about anything in your payload. `subsidiary` on NetSuite is the live case: it is mirrored inbound and has no write-back path, and neither do NetSuite’s other setup lists such as `accountingPeriod` and `currency`, so a step that tries to create one is refused. The chart of accounts is **not** among them: `account` on NetSuite is writable, so accounts can be migrated like any other record. The refusal arrives at the first step rather than half-way through a run, which is the right failure — but reading a record type’s direction in the [data model](/tenant/data-model/) first is cheaper than discovering it. The same refusal covers a record type the target system does not have **at all**, not only one it holds read-only. Record types are not global: a message belongs to the systems that carry messages, and naming one in a step that targets a system without them is refused here with the same `WRITE_REFUSED` and the same sentence. Which record types a system has is what [the data model](/tenant/data-model/) lists per source. ## Nothing migrates until the target’s write-back is on [Section titled “Nothing migrates until the target’s write-back is on”](#nothing-migrates-until-the-targets-write-back-is-on) Write-back ships **off** for every source, so a new instance is read-only *towards* the system you are migrating into. While it is off, the first step of the first run is refused at the write boundary before anything is created: the run ends `failed`, the step’s ledger row carries `SYNC_BIDIRECTIONAL_DISABLED` with a message telling you to contact us, and its `pg_row_id` is null. Turn write-back on for the **target** system before you migrate anything — this is the first thing a migration runs into, not the last. The rollback reads the same entitlement. `onFailure: 'rollback'` deletes what the run created, newest first, through the delete boundary, and that boundary asks the same question the write asked. So if write-back is switched off *between* a run’s writes and its rollback, the undo cannot run: the run ends `failed` with a reason beginning `rollback incomplete`, and the records it created are still live. A timed-out `awaitSource` step reaches that same `rollback incomplete` ending by a different route, and that one needs no flag change. Its record is still pending on the trail with no verdict, so the rollback deliberately leaves it rather than tombstone a record the source may be about to create. ## Before you run one [Section titled “Before you run one”](#before-you-run-one) * Turn write-back on for the target system. With it off nothing is created at all — the first step is refused. * Read the direction of every record type your steps name. A read-only type is a wall, not a slow path. * Decide your re-run story. Nothing keys idempotency on the source row. * Leave `awaitSource` off unless a later step needs the id. * Run it for a handful of rows first and read each run back — `turbobase processes runs` or `GET /v1/processes/runs/:runId` — before you turn the volume up. There is no offline dry-run for a process: `ext test` and `ext replay` cover hooks and conduits, and [`turbobase sandbox`](/extending/sandboxes-and-testing/#turbobase-sandbox--ephemeral-local-authoring-instances) does not seed an instance yet. A few rows against the real target is the rehearsal that exists. ## Next steps [Section titled “Next steps”](#next-steps) * [Writing processes](/extending/writing-processes/) — the full `defineProcess` contract. * [Writing conduits](/extending/writing-conduits/) — bridge a record between sources as it arrives, rather than in bulk. * [Data model](/tenant/data-model/) — which record types are bidirectional, and what write-back is. * [Sandboxes and testing](/extending/sandboxes-and-testing/) — how extensions execute, and the offline dry-runs that exist for hooks and conduits. # Real-time sync from your own NetSuite scripts > How Turbobase picks up NetSuite changes in real time, when it can't, and the two-line notify call your SuiteScripts can use to close the gap. Shipped Turbobase keeps your Postgres mirror current in two ways: a **real-time push** from Oracle NetSuite the moment a record is saved, and a **periodic sweep** every four hours that catches anything the push missed. The push is what makes your data feel live; the sweep is a safety net, not the plan. The sweep reads what changed in bulk through SuiteQL rather than one record at a time, so it finishes in minutes on a busy account, and if a sweep or a first load is interrupted it saves its place and resumes automatically within a few minutes. This page is for NetSuite developers with their own SuiteScripts in the account. It covers what the push already handles (more than most people expect), the cases it genuinely cannot see, and the one-line call that closes them. ## What is already covered [Section titled “What is already covered”](#what-is-already-covered) When your Turbobase bundle is installed, it deploys a User Event script for every record type you sync. Those deployments are released for **every NetSuite execution context**, so a save reaches Turbobase in real time no matter what performed it: | How the record was saved | Real-time push? | | ------------------------------------------------------------------ | --------------- | | A user in the NetSuite UI | Yes | | Your Suitelet calling `record.save()` | Yes | | A scheduled or Map/Reduce script | Yes | | A workflow action | Yes | | A RESTlet or SOAP/REST web services call | Yes | | `record.submitFields()` / inline edit | Yes | | CSV import **with** “Run Server SuiteScript and Trigger Workflows” | Yes | Note **You probably do not need to change your scripts.** A Suitelet that creates transactions with `record.save()` already triggers the push. Adding a notify call there is harmless — the duplicate is discarded — but it is not what makes the record sync. ## What is not covered [Section titled “What is not covered”](#what-is-not-covered) Five cases. The first four are NetSuite not telling Turbobase anything; the fifth is a push that did arrive, carrying a value NetSuite had not written yet. 1. **CSV import with server scripts switched off.** The import assistant’s “Run Server SuiteScript and Trigger Workflows” option is per-import. With it off, no User Event runs for any of the imported rows. 2. **Parent records NetSuite recalculates behind the scenes.** Creating an item fulfillment moves its sales order to *Pending Billing*; creating a vendor bill moves its purchase order to *Fully Billed*. NetSuite rewrites the parent without saving it, so no User Event fires on the parent. *Turbobase handles the common ones for you* — eight standard pairs, found through the child’s **Created From** link — so for those the parent is re-read seconds after the child and there is nothing to do. It is still worth knowing why the parent’s own script never ran. **Outside those pairs, ask us to mark the relation.** Your own record types are never one of the eight, and a link that is not *Created From* — a custom body or custom record field pointing at the record NetSuite rewrites — is not the one they follow. Tell support which record makes NetSuite recalculate which, and we mark that relation on your instance; from then on the recalculated record is re-read seconds after the one that moved it, instead of waiting for the next four-hourly refresh. It is a setting on our side, not a script change on yours. 3. **Record types you have not enabled.** Only the record types listed on your Turbobase Configuration record push at all. 4. **Anything outside NetSuite** — a middleware job or partner system that writes through an integration you control. 5. **A document number that arrives as “To Be Generated”.** This one is not a missing push — the push arrived within seconds, and the number was still the placeholder. NetSuite assigns the real number when it commits the record, which is after the point it tells us about the save, so what we are handed is the form’s placeholder. *Your tenant now asks NetSuite for the committed value before it stores anything*, so the real number arrives on the first message. That covers the document number on a transaction, the separate transaction number on a check, the identifier NetSuite assigns a new customer, vendor, contact, partner, project or employee, and NetSuite’s own last-modified stamp. **This needs bundle TB 2.13.0 or later in your NetSuite account.** On an earlier bundle the placeholder stands until the next four-hourly refresh; there is nothing to change in your own scripts either way, and a record that was already stored with a placeholder is corrected the next time it changes or the refresh re-reads it. Check your bundle version under **Customization → SuiteBundler → Search & Install Bundles → List**, and ask support to upgrade it. A value NetSuite *computes* rather than stores — a running total, a balance — is not on the record at save time at all, so no read can reach it and it still waits for the refresh. **Your instance names the record types this is happening to.** Press **How to fix** on [Late arrivals](/tenant/source-health/) and, where the realtime path is plainly delivering but certain records keep coming in on the scheduled catch-up, the panel lists exactly which record types — so you can go to the scripts that save those and nothing else, rather than auditing every record type you have. Clicking one of the late rows shows which fields the catch-up moved, which tells a real edit apart from a change nothing on screen would show. ## The notify call [Section titled “The notify call”](#the-notify-call) For cases 1 and 4, tell Turbobase directly. Add the module to your script’s `define` list and call it after your write: ```javascript define(['N/record', '/SuiteScripts/tb/lib/tb_notify'], function (record, tb) { 'use strict'; function onRequest(context) { var soId = record.submitFields({ type: 'salesorder', id: context.request.parameters.id, values: { custbody_shipment_status: 'SHIPPED' } }); tb.notify('salesorder', soId); // ← the whole integration } return { onRequest: onRequest }; }); ``` If you already have the record loaded, pass it and skip the reload: ```javascript var rec = record.load({ type: 'salesorder', id: soId }); // ... your changes, then rec.save() ... tb.notify('salesorder', soId, { record: rec }); ``` **`tb.notify(recordType, id, options)`** | Argument | Meaning | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `recordType` | NetSuite record type id — `'salesorder'`, `'inventoryitem'`, `'customrecord_my_type'`. Use the SuiteScript spelling, the same string `record.type` returns. | | `id` | Internal id of the record. | | `options.record` | Optional loaded record, to avoid a reload. | Returns `true` when an update was sent, `false` when it was skipped. It never throws. Caution There is no `item` record type in NetSuite. Use the concrete type — `inventoryitem`, `noninventoryitem`, `serviceitem`, `kititem`, `assemblyitem`. ### What it guarantees [Section titled “What it guarantees”](#what-it-guarantees) * **It never breaks your script.** Delivery is fire-and-forget and every failure path is caught and logged. Your save cannot fail because Turbobase was unreachable. * **It never blocks.** No waiting on a round trip. * **It respects your configuration.** A record type you have switched off stays off — this call cannot re-enable it. * **It cannot loop.** Records Turbobase itself wrote are skipped, and a notify that duplicates a User Event on the same save collapses into a single update. ### Cost [Section titled “Cost”](#cost) About 20 governance units, or 30 if Turbobase has to load the record for you — against the 1,000 a Suitelet gets, or the 200 a User Event gets. ## Calling it from somewhere that can’t import a module [Section titled “Calling it from somewhere that can’t import a module”](#calling-it-from-somewhere-that-cant-import-a-module) Client scripts and workflow action scripts can use the **TB Notify** Suitelet instead — anything running inside NetSuite with the user’s session: ```javascript require(['N/https', 'N/url'], function (https, url) { https.post.promise({ url: url.resolveScript({ scriptId: 'customscript_tb_io_notify', deploymentId: 'customdeploy_tb_io_notify' }), body: JSON.stringify({ recordType: 'salesorder', id: soId }), headers: { 'Content-Type': 'application/json' } }); }); ``` It replies `{ "ok": true, "sent": true }`, or `{ "ok": true, "sent": false, "reason": "skipped" }` when the record type is not enabled or the change was Turbobase’s own write. The Suitelet requires a NetSuite **session** and runs under the caller’s role. It is not available without login, so it is **not reachable from outside NetSuite** — token-based (TBA) credentials authenticate RESTlets, not Suitelets. For an external system, have it call your own integration and use the library from a server-side script there, or ask us for a RESTlet endpoint. Note **Server-side scripts should import `lib/tb_notify` rather than call the Suitelet.** The library runs in your script’s own execution — no second HTTP round trip inside NetSuite, and no extra Suitelet governance. The Suitelet exists for callers that cannot take a file-cabinet dependency. ## Seeing which records are missing the push [Section titled “Seeing which records are missing the push”](#seeing-which-records-are-missing-the-push) Your instance’s **Late arrivals** tab (**/data/sync/late-arrivals**) lists the records the four-hourly sweep delivered first — so no real-time push arrived for them. That is the list of records hitting one of the four cases above, by record type and by whether the change was a create, an edit or a deletion, with each record type’s real-time rate beside the count. Start there rather than guessing which of your scripts needs the notify call: a record type sitting well below 100% is where it is worth adding. A record the push already delivered is re-read by the sweep, found unchanged, and does not appear. See [Source health](/tenant/source-health/) for the full description of the tab. ## Checking it worked [Section titled “Checking it worked”](#checking-it-worked) Your instance’s **Source health** page shows inbound webhook volume and any User Event errors NetSuite logged. If a notify call is not landing, turn on **Debug mode** there: NetSuite then logs every trigger and the reason for any skip (`not enabled`, `echo`, `no synced-field change`) to the script execution log, so you can see which gate a save is hitting. # Sandboxes and testing > Dry-run extensions in the isolated-vm code sandbox and stand up ephemeral local authoring instances before deploying. Shipped Before an extension ever reaches a live instance, you test it. Turbobase gives you two complementary tools: an **execution sandbox** that runs your extension’s code exactly the way production does, and **ephemeral local authoring instances** you can stand up from a sampled slice of real data. This page disambiguates the two senses of the word “sandbox” and walks the testing commands. ## Two senses of “sandbox” — don’t conflate them [Section titled “Two senses of “sandbox” — don’t conflate them”](#two-senses-of-sandbox--dont-conflate-them) | Term | What it is | | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Code sandbox** (this page) | The `isolated-vm` runtime that *executes* a hook or conduit — a fresh V8 heap, hard memory + CPU caps, **no IO, no secrets**. The same isolate runs an extension in production, under `turbobase ext test`, and under `turbobase ext replay`. | | **`turbobase sandbox …`** (this page) | An *ephemeral local authoring instance* — a throwaway local database seeded with a sampled, redacted slice of a live instance, with your `hooks/` + `conduits/` mounted, that reaps itself after a TTL. | | **An Oracle NetSuite (or other source) sandbox account** | A *provider* concept: your ERP’s non-production account. Unrelated to either of the above; you wire one up when [setting up a NetSuite connection](/netsuite-oauth-setup/). | The first two are Turbobase mechanisms; the third is your source provider’s. When this page says “sandbox” with no qualifier, it means the code sandbox. ## The code sandbox — how extensions execute [Section titled “The code sandbox — how extensions execute”](#the-code-sandbox--how-extensions-execute) Every extension is untrusted customer / AI-authored code, so the runtime never runs it as a live in-process closure. Instead: 1. **esbuild bundles** the extension’s TypeScript into one self-contained ESM module. An extension may import the SDK factory (`@turbobase/extensions` / `@/sync/hooks` / `@/sync/conduits` / `@/sync/processes`), which is resolved to a tiny inline identity stub, and a **relative sibling inside its own directory** (`./shared-rule.js`), which is folded into the bundle so the isolate still receives one module. Any **other** import — an npm package, a Node builtin, a path that escapes the extension’s directory — fails the bundle with a clear error (the “no shared-lib import” fence). 2. The bundle runs inside an **`isolated-vm` Isolate**: a fresh V8 heap with a **16 MB** memory cap and a **200 ms** per-call CPU/wall timeout, **no Node builtins, no IO, no module resolution**. The only host surface reachable from inside is the documented `HookContext` — `reject` / `patch` / `log` plus the read context — bridged across the isolate boundary. 3. A throw, an OOM, or a runaway loop surfaces as a thrown Error the executor handles exactly as it handled an in-process throw: **fail-open** by default, or, for a `failClosed` extension, **the operation is refused as a non-verdict** — `503 hook_unavailable`, retried rather than reported as a validation failure, because an extension the isolate had to kill reached no opinion about the record. Only `ctx.reject` produces a `422`. See [fail-open vs fail-closed](/extending/writing-hooks/#fail-open-vs-fail-closed). > The bridged context exposes **no `secrets`**. The isolate cannot reach `process.env`, the filesystem, or the network — there is nothing to leak even if an extension tried. Because `turbobase ext test` and `turbobase ext replay` reuse **the same bundle, the same isolate, and the same effect envelope**, a local dry-run and a production firing share one execution path. What passes locally behaves identically deployed. ## `turbobase ext test` — dry-run against samples [Section titled “turbobase ext test — dry-run against samples”](#turbobase-ext-test--dry-run-against-samples) > **First run on a fresh install?** `ext test` and `ext replay` compile and execute your extension, which needs two native packages the one-line installer leaves out. Fetch them once with `turbobase ext extras install` (`turbobase ext extras status` reports what you have). An `npm install -g @turbobase/cli` already has them. Every other command works without them. Run an extension against fixtures in `samples/`: ```sh turbobase ext test hooks/customer.before_save.ts # PASS customer-company # FAIL customer-individual-missing-last (rejected: MANDATORY_FIELD_MISSING) # # 1/2 sample(s) passed. ``` Each fixture is one case; the command exits non-zero on any failure (so it doubles as a CI gate). Generate fixtures from the live instance catalog with [`turbobase project samples`](/cli/reference/); point at a different directory with `--samples `. For machine-readable CI output: ```sh turbobase ext test hooks/customer.before_save.ts --reporter junit > results.xml turbobase ext test hooks/customer.before_save.ts --reporter json ``` ## `turbobase ext lint` — offline static analysis [Section titled “turbobase ext lint — offline static analysis”](#turbobase-ext-lint--offline-static-analysis) `lint` catches the semantic foot-guns the Zod schema can’t — a weak conduit `idempotencyKey`, a missing `createdFrom`, an extreme `cycleBudget`, a same-source “conduit.” No instance, no DB, no network: ```sh turbobase ext lint conduits/shop2ns.order.ts turbobase ext lint conduits/shop2ns.order.ts --ci # exit non-zero on any warning ``` It reads a hook and a process too, and each rule applies only to the kinds it is about: the four above describe a cross-source bridge, so they are raised on a conduit only, while the deploy-identity check is raised on all three. So `--ci` is safe to put in a deploy lane that ships every kind — a correct module of any of them exits 0. ## `turbobase ext replay` — drive a conduit’s lifecycle [Section titled “turbobase ext replay — drive a conduit’s lifecycle”](#turbobase-ext-replay--drive-a-conduits-lifecycle) `replay` is the conduit’s dry-run. It drives the conduit through dispatch guards → `from.when` → `transform` → apply-branch → bindings: ```sh turbobase ext replay conduits/shop2ns.order.ts --fixture samples/order.json --trace ``` * **`--fixture `** (offline, default) runs `when` + `transform` through the **same isolate** the engine’s untrusted path uses; the apply branch is the shared pure rule. No DB, no network. * **`--against sandbox`** (online) runs the fuller engine path against a running local sandbox (requires a local Postgres); it defers with a clear reason when no local DB is present. `--trace` emits the per-stage trace; `--reporter junit|json` emits one case per stage. ### Replaying a conduit that reads [Section titled “Replaying a conduit that reads”](#replaying-a-conduit-that-reads) A conduit that declares [`reads`](/extending/writing-conduits/#ctxquery--one-bounded-declared-read) looks something up while it runs, and offline there is nothing to look it up in. So the fixture answers the read: add a **`queryRows`** map, keyed by the PostgREST path-and-query string your transform passes to `ctx.query` — the whole string, exactly as you wrote it: ```json { "fromSource": "slack", "recordType": "channel_message", "externalId": "C09ABCDEF:1759000111.000200", "payload": { "scopeRef": "C09ABCDEF", "metadata": { "threadTs": "1759000000.000100" } }, "queryRows": { "channel_message?select=external_id,body&external_id=eq.C09ABCDEF%3A1759000000.000100&limit=1": [ { "external_id": "C09ABCDEF:1759000000.000100", "body": "acme/storefront#412 — thread opened" } ] } } ``` Three rules, and the second is the one that makes this workable: * **The key is compared verbatim.** Your transform usually composes its query out of the payload, so the key is whatever that composition produces — percent encoding and all. Nothing normalizes it for you. * **A key you did not supply answers `[]`**, and `--trace` names it. That is the loop: replay once with no `queryRows`, read the strings your conduit actually asked for off the trace, and paste them in. * **Rows are served only to a conduit that declared `reads`.** One that declared none has no `ctx.query` at all, offline and deployed alike, however much the fixture offers — so rows in a fixture do not buy a read the live conduit would not get. Replay reads that declaration off your file, so write `reads:` as a literal array on a line of its own, the way the reference conduit does. A `reads` assembled from a variable, or a whole definition squeezed onto one line, reads as *no reads declared* offline — you get `ctx.query is not a function` from a conduit that works once deployed. `--trace` prints one line per read, in the order the conduit made them — the `from.when` gate’s included, since a gate may read too: ```plaintext ctx.query (declared reads): channel_message?select=external_id,body&external_id=eq.C09ABCDEF%3A1759000000.000100&limit=1 → served, 1 row(s) contact?select=external_id,email&external_id=eq.USERX → not served by the fixture, 0 row(s) ``` That section prints whatever the conduit then does, which is what makes the first replay useful: a read your fixture has not answered yet often stops the conduit dead — the reference reading conduit refuses an empty root outright. The run ends in an error, the error is the trace’s last line, and the strings are still above it: ```plaintext ctx.query (declared reads): channel_message?select=external_id,body&external_id=eq.C09ABCDEF%3A1759000000.000100&limit=1 → not served by the fixture, 0 row(s) ERROR — slack2gh: no mirrored thread root for C09ABCDEF:1759000000.000100 ``` Without `--trace`, that run prints the one error line and nothing else. A served read does **not** mean the live read would be allowed: the declaration checks — an undeclared resource or column, a filter outside `reads[].by`, the per-run query budget — are the engine’s, and replay does not mirror them. Keep the fixture’s keys inside what `reads` declares, and read the refusal table in [Writing conduits](/extending/writing-conduits/#ctxquery--one-bounded-declared-read). ## `turbobase sandbox` — ephemeral local authoring instances [Section titled “turbobase sandbox — ephemeral local authoring instances”](#turbobase-sandbox--ephemeral-local-authoring-instances) When you want to author against something that feels like a real instance — real record shapes, real volume — without touching production, stand up a local sandbox seeded from a sampled, redacted slice of an instance: > **Not available yet.** `turbobase sandbox create` refuses and creates nothing. Seeding needs a per-column PII classification for the source instance’s tables, and redaction fails closed on any column it cannot prove is safe — so until that classification exists, a sandbox could only ever be empty or unsafe. Use [`ext test`](#turbobase-ext-test--dry-run-against-samples) and [`ext replay --fixture`](#turbobase-ext-replay--drive-a-conduits-lifecycle) above; both run offline and cover the authoring loop. The rest of this section describes the intended shape. ```sh turbobase sandbox create --from acme --ttl 72h --sample 2% # sandbox acme-72h-abc ready. # source: acme (sampled 2%, redacted) # url: http://acme-72h-abc.localhost:… # expires: 2026-06-11T… ``` `create` copies a sampled, **redacted** slice of `--from` and stamps a TTL. Crucially, the sandbox process forces a sandbox mode that resolves every source connector to a mock / fail-closed stub — **no code path in a sandbox reaches a real NetSuite or Stripe**. A sandbox is **local-only by construction**: `create`, `destroy` and the reaper all refuse any target that isn’t a localhost database. List and reap: ```sh turbobase sandbox list # active sandboxes; reaps any past their TTL turbobase sandbox destroy acme-72h-abc # drop the DB + remove from the registry ``` `list` and `destroy` both opportunistically reap expired sandboxes, so a forgotten sandbox doesn’t linger past its TTL. ## A typical loop [Section titled “A typical loop”](#a-typical-loop) 1. `turbobase ext new hook …` (or `new conduit`) — scaffold. 2. `turbobase project samples` — pull fixtures from the instance catalog. 3. `turbobase ext lint ` — catch foot-guns offline. 4. `turbobase ext test ` (or `replay` for conduits) — dry-run in the isolate. 5. `turbobase sandbox create --from ` — exercise against realistic data. 6. [`turbobase ext deploy`](/extending/deploy-plan-promote/) — ship it. ## Next steps [Section titled “Next steps”](#next-steps) * [Writing hooks](/extending/writing-hooks/) / [Writing conduits](/extending/writing-conduits/) — the authoring contracts. * [Deploy, plan, promote](/extending/deploy-plan-promote/) — the rollout workflow. * [NetSuite OAuth setup](/netsuite-oauth-setup/) — wiring a source provider’s sandbox account. # Writing conduits > Author conduits that bridge a canonical record from one connected source into another with the defineConduit contract. Shipped A **conduit** is the cross-source counterpart to a [hook](/extending/writing-hooks/). A hook transforms a record on **one** source’s write path; a conduit routes and transforms a canonical record from one source into **another**, with the canonical row as the interchange format: “a paid Shopify order should become an Oracle NetSuite sales order,” “a NetSuite item fulfillment should become a Shopify fulfillment.” It’s authored with the same SDK, validated by the same Zod machinery, run in the same isolated-vm sandbox, and stored in the same DB-native store — a conduit is “a hook that bridges sources,” not a separate subsystem. Both halves ship today: the authoring surface (the `defineConduit` SDK, the Zod schema, the registry entry, the CLI/MCP commands) and the **engine** that runs conduits — dispatch, binding, fan-out and conflict handling. The SDK is the same `@turbobase/extensions` npm package hooks use — see [Install the SDK](/extending/writing-hooks/#install-the-sdk) for local typechecking (`@turbobase/extensions/conduit` is the conduit-only subpath export). ## The `defineConduit` contract [Section titled “The defineConduit contract”](#the-defineconduit-contract) ```ts import { defineConduit } from '@turbobase/extensions'; export default defineConduit({ id: 'shop2ns:order', // '2:' on: 'after_canonicalize_inbound', // the cross-source lifecycle event from: { source: 'shopify', // origin source recordType: 'order', // canonical record type to match when: (ctx) => ctx.payload.financial_status === 'paid', // optional gate }, to: { source: 'netsuite', // target source the master fans out to recordType: 'salesOrder', // canonical record type to create }, mode: 'dual-bind', // default; or 'one-shot' idempotencyKey: (ctx) => `shop2ns:order:${ctx.externalId}`, cycleBudget: 4, // default 4 conflictStrategy: 'merge', // default 'merge' transform: (ctx) => ({ patch: { // canonical-in → canonical-patch-out (pure) memo: `from Shopify order ${ctx.externalId}`, }, createdFrom: { source: ctx.fromSource, recordType: ctx.recordType, externalId: ctx.externalId, }, }), }); ``` | Field | Required | Meaning | | ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | yes | Stable id; collisions are loader errors. Convention `'2:'` (e.g. `shop2ns:order`). | | `on` | yes | The lifecycle event — `after_canonicalize_inbound`, `after_sync_success_outbound`, `after_save`, or `after_delete`. | | `from` | yes | `{ source, recordType, when? }` — which inbound record triggers it, with an optional payload gate. | | `to` | one form | `{ source, recordType }` — the target the master materializes into. One `transform` emits **one** target record type. | | `transform` | one form | Pure `ctx → { patch, createdFrom? }`. Returns a canonical patch + the lineage pointer. | | `sequence` | the other form | An ordered list of `{ to, transform, awaitSource? }` entries, materialized one after another on the same inbound record — see [several targets, in order](#several-targets-in-order). Declare **either** `to` + `transform` **or** `sequence`, never both. | | `mode` | no | `'dual-bind'` (default — keep both sides synced) or `'one-shot'` (materialize once, no ongoing binding). | | `idempotencyKey` | no | Dedups a replayed source webhook; anchors the `conduit_event` audit row. Convention `':'`. | | `cycleBudget` | no | Max-hop safety fuse on top of the loop guards. Default 4. | | `conflictStrategy` | no | What happens when a fanned-out write is rejected — see [conflict handling](#conflict-handling). Default `'merge'`. | | `timeoutMs` | no | Execution-budget override; default 200ms. | | `description` | no | Operator-friendly text in the UI. | | `systemReserved` | no | Managed-service guardrail instance admins can’t disable (mirrors hooks). | ## Several targets, in order [Section titled “Several targets, in order”](#several-targets-in-order) One record arriving in one system often has to become **several** records in another, and the order matters: the sales order before the deposit that applies to it, the invoice before the payment. Declare that as a `sequence` instead of a single `to` + `transform`: ```ts import { defineConduit } from '@turbobase/extensions'; export default defineConduit({ id: 'shop2ns:order-and-deposit', on: 'after_canonicalize_inbound', from: { source: 'shopify', recordType: 'order', when: (ctx) => ctx.payload.financial_status === 'paid' }, sequence: [ { to: { source: 'netsuite', recordType: 'salesOrder' }, awaitSource: true, // hold the next entry until NetSuite has numbered this one transform: (ctx) => ({ patch: { memo: `from Shopify order ${ctx.externalId}` }, createdFrom: { source: ctx.fromSource, recordType: ctx.recordType, externalId: ctx.externalId }, }), }, { to: { source: 'netsuite', recordType: 'customerDeposit' }, transform: (ctx) => ({ patch: { amount: ctx.payload.total_price, sales_order_id: ctx.materialized[0].externalId, // the id NetSuite minted for the entry above }, createdFrom: { source: ctx.fromSource, recordType: ctx.recordType, externalId: ctx.externalId }, }), }, ], }); ``` What the engine guarantees for a `sequence`: * **Declared order.** Entries run one after another, on the server, for one inbound record. Each entry’s `transform` sees `ctx.materialized` — the targets the run has already landed, in order, as `{ source, recordType, masterTable, masterRowId, externalId }`. It is empty for the first entry. * **The minted id, when you ask for it.** `awaitSource: true` on an entry holds the *next* entry until the target source has given its verdict on this one, so `ctx.materialized[i].externalId` carries the id the source minted. Without it the id is `null` — the write is still on its way. The wait is the same one a [process](/extending/writing-processes/) step uses, with the same five-minute budget, and it reads the same rule: a retrying write is not a refusal. It applies to a **different-type** target only — the one that mints a new record. An entry of the firing record’s own type merges onto the firing master, so there is no minted id to wait for, and `awaitSource` on it is refused at deploy. * **One ledger row per target.** The first entry’s `conduit_event` row carries the conduit’s idempotency key; later entries carry `#2`, `#3`, … so `turbobase logs --conduit ` shows every target’s disposition. All rows sit at the **same hop**: a declared fan-out is siblings on one hop, not a chain, and does not spend the cycle budget as though it were a loop. * **Each target is checked on its own.** Every `to` has to be [writable](#the-target-must-be-writable); a sequence whose second target is read-only is refused at deploy naming that pair. An entry that declares `awaitSource` against a record type with no write trail is refused too (`conduit_target_no_write_trail`), as is one that declares it on a target of the firing record’s own type (`conduit_target_await_same_type`). * **A failure stops the sequence and undoes nothing.** When an entry fails — the source refused it, no verdict arrived inside the budget, or its target could not be resolved — that entry’s row is `failed` with the reason, every later entry is `skipped` with `earlier target failed`, and a `sync_failure` is raised. What already materialized **stays**: a conduit has no compensating delete, and a half-materialized sequence is visible on the ledger, one row per target, rather than hidden. If you need the undo, that is a [process](/extending/writing-processes/) with `onFailure: 'rollback'`. * **Resumable.** A re-delivered run skips every entry whose row is already `committed` and continues from the first one that is not, so a retry never mints a second master for a target that already landed. The apply rule is unchanged per entry: a target of the **same** canonical type as the firing record binds it to the same master; a **different** type mints a new master chained to the origin by `createdFrom`. `turbobase ext replay` and `turbobase ext lint` understand both forms. ## The target must be writable [Section titled “The target must be writable”](#the-target-must-be-writable) `to` is the half the bridge **writes**. Turbobase materializes the canonical master and the existing write-back worker fans it out to `to.source` — so a target whose adapter declares no PG→source write path for that record type has nothing to fan out to, and every run of the conduit would fail after the master had already been flipped. That pair is therefore **refused at deploy time**, before the conduit is stored: ```sh turbobase ext deploy conduits/ns2slack.message.ts # 400 conduit_target_read_only # conduit target (slack, message) is declared read-only: the slack adapter has # no PG→source write path for message, so the bridge would flip the master row # and then lose every write to it ``` The refusal body carries `error: "conduit_target_read_only"`, `toSource`, `toRecordType` and that `reason`, so a script can branch on it. The same check runs when the assistant drafts a conduit — an unshippable target is refused before a module is written — and again at apply time, which catches a conduit deployed before this rule existed. Two targets are **not** refused, and the distinction matters if you are writing a bridge into custom data: * a pair the adapter declares **bidirectional** — the ordinary case; * a pair with **no static declaration at all**, which is what the per-install `cr_` / `cl_` custom-record mirrors are. Those are writable by construction and have nowhere to say so, so a conduit targeting one deploys normally. To check a pair before you author against it, read `GET /v1/catalog/records` (served to an MCP client as `catalog:///`) and look at `writeCapability`. A non-null value means the write path exists and this tenant may use it, so the pair is a valid `to`. A `null` is the one to read carefully: it covers both “the adapter declares this record read-only”, which is what the deploy refuses, and “write-back is not switched on for this tenant yet”, which is an entitlement and not a property of the conduit. ## Starting a process instead of writing a record [Section titled “Starting a process instead of writing a record”](#starting-a-process-instead-of-writing-a-record) A conduit’s `to` can name a [process](/extending/writing-processes/) rather than a record type: ```ts to: { source: 'turbobase', recordType: 'process', process: 'acme:reorder-suggestions' }, ``` The transform’s patch becomes the process **input** — so the transform is where you shape the firing record into whatever the process declares it takes — and the run is recorded on the conduit ledger like any other target. The process runs as a process always does: its steps go through the write boundary, and its run is watched at `GET /v1/processes/runs/:runId`. A process your instance has not got is refused at `turbobase ext deploy`, naming it. `turbobase` is a reserved source for the platform’s own records, not a connector. Use it only in the forms these docs describe. ## The four events [Section titled “The four events”](#the-four-events) ```ts // exported from @turbobase/extensions export const CONDUIT_EVENTS = [ 'after_canonicalize_inbound', 'after_sync_success_outbound', 'after_save', 'after_delete', ] as const; ``` The first two fire **after** a source record’s sync commits — the natural triggers for “source A landed, now drive source B”: * **`after_canonicalize_inbound`** — after an inbound source webhook is canonicalized and upserted into the PG mirror. The trigger for “a record arrived from source A; materialize it into source B.” * **`after_sync_success_outbound`** — after an outbound write-back commits to the source. The trigger for the next leg of a flow (NS `itemFulfillment` committed → push the fulfillment to Shopify). The other two fire on a record **here**: * **`after_save`** — after a record is saved on your instance and the save has committed, whoever saved it: your app through the write boundary, a process, the AI assistant, Studio, or another conduit. The trigger for “someone changed something here; drive source B.” A record *arriving* from a connected source is not a save in this sense — it keeps `after_canonicalize_inbound`, so a synced record never fires twice. * **`after_delete`** — after a record is **deleted** on your instance and the tombstone has committed. The trigger for “unpublish the counterpart”, “close the ticket”, “retract the announcement” — every flow that has to undo something the instance previously drove. It fires on the TRANSITION only, so a repeat delete of a record that is already gone (still a `200`, because a delete here is idempotent) does not fire a second time, and a delete your guardrails or a `before_delete` hook refused fires nothing at all. Conduits run **asynchronously** on all four — never inline on the ingest/write-back path, never inline on the save, and never inline on the delete. ### What an `after_delete` run is told [Section titled “What an after\_delete run is told”](#what-an-after_delete-run-is-told) `ctx.payload` is the record’s **last state** — the row as it stood before the tombstone, which is the one thing a deletion reaction cannot read back for itself: by the time your conduit runs the row is a tombstone. `ctx.externalId` addresses it the same way a save does, its external id where it has one and its surrogate key otherwise, and `ctx.savedBy` names the writer that made the delete on the same vocabulary as a save. `ctx.change` is **absent** on this event, as it is on the two inbound ones: a delete is neither an insert nor an edit and wrote no fields, so there is nothing for `fields` to name. ### What an `after_save` run is told [Section titled “What an after\_save run is told”](#what-an-after_save-run-is-told) Two extra context fields come with this event, and both are read by `from.when` as well as by `transform`: * **`ctx.change`** — `{ kind: 'insert' | 'update', fields: [...] }`. `fields` names the canonical columns the writer supplied, so `ctx.change.fields.includes('status')` is the gate for “run when the status changes” rather than something your body works out. * **`ctx.savedBy`** — `{ kind: 'app' | 'process' | 'agent' | 'studio' | 'conduit' | 'user', id? }`, carrying the conduit’s id when a conduit made the save. A conduit whose own write would fire it again refuses it here: ```ts from: { source: 'standalone', recordType: 'work_item', when: (ctx) => ctx.savedBy?.id !== 'tidy:work_item', }, ``` That refuses the save before the run starts. The cycle budget also stops a loop, but it stops it by tripping — after the conduit has already run. Both are **absent** on the two inbound events rather than guessed, so a conduit written before they existed reads exactly what it read before. ## Conduits are pure and credentials-free [Section titled “Conduits are pure and credentials-free”](#conduits-are-pure-and-credentials-free) A conduit body is a pure canonical→canonical transform. `ConduitContext` has **no `secrets`**: it reads a pre-resolved context and **returns** a canonical `patch` plus a target — it never calls a source API, never holds source credentials, never touches an env var or the secrets backend. The engine writes the canonical master row (`originating_system='hybrid'`) and the existing write-back worker fans it out to the bound source(s). The read context gives you `recordType`, `event`, `fromSource`, `externalId`, `payload`, `lines`, `tenantConfig`, the current `bindings` (on a master a conduit MINTED, that is the target source and nothing else — the system the record came from is not bound to it, and `created_from_id` is what names it), an `atlas` entity resolver (read-only, pre-resolved cross-source id mapping), a `canonicalStatus(...)` status-normalization helper, `log(...)`, and — when you declare it — `query(...)`. ### `ctx.query` — one bounded, declared read [Section titled “ctx.query — one bounded, declared read”](#ctxquery--one-bounded-declared-read) Some bridges cannot be written from the trigger’s payload alone. A reply on a Slack thread carries the thread’s root timestamp and nothing that names the GitHub issue it belongs to; resolving it is one keyed lookup. A conduit that cannot make it has to be a scheduled digest instead of a conversation. So a conduit may **declare** what it reads, and read exactly that: ```ts export default defineConduit({ id: 'slack2gh:comment', on: 'after_canonicalize_inbound', from: { source: 'slack', recordType: 'channel_message' }, to: { source: 'github', recordType: 'comment' }, // Declared up front, so it is reviewable in this file rather than // discovered at runtime. reads: [ { recordType: 'channel_message', columns: ['external_id', 'metadata'], by: ['external_id'] }, { recordType: 'channel', columns: ['external_id', 'name'], maxRows: 50 }, ], maxQueriesPerRun: 4, transform: async (ctx) => { const rootId = `${ctx.payload.scope_ref}:${ctx.payload.metadata.threadTs}`; const [root] = await ctx.query( `channel_message?select=external_id,metadata&external_id=eq.${rootId}&limit=1`, ); // …build the canonical patch from the root the thread describes. }, }); ``` `q` is one PostgREST path-and-query, the same shape `defineProcess`’s `ctx.query` takes. The supported subset is `select`, `limit`, `offset`, `order` and simple column filters — `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `is`, `in`. **What is refused, and it is always refused BY NAME:** | Refused | Because | | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | | A resource not in `reads` | The declaration is the boundary. The message lists what you did declare. | | A column not in `reads[].columns` | Same, for the columns you select. | | A filter on a column not in `reads[].by` | Filtering is a separate power from reading — `by` is a second gate, not a restatement of `columns`. | | `select=*` and embeds | A declaration that promises nothing is not a declaration. | | An operator outside the list above | A silently dropped filter returns MORE rows — the failure an author never sees in a passing test. | | More than `maxQueriesPerRun` reads | The budget belongs to the RUN, so a `sequence` shares one across its entries. | **Two things the engine adds to every read**, because forgetting either returns wrong rows rather than an error: * the **type discriminator** on a polymorphic table — `channel_message` lives in the shared `activity` table, so a read without `activity_type` would also return calls and events; * the **connection scope** on a connection-scoped table, so a tenant holding two NetSuite connections cannot read the other one’s rows. You cannot opt out of either, and you do not have to remember them. **Why it is not scoped by RLS.** A process’s `ctx.query` runs as the invoking user. A conduit has no invoking user — it fires off a sync event — so there is no principal for RLS to scope, and running the read under a claimless role would deny every row. The declaration is the boundary instead. That is not a widening of trust: the engine already mints canonical master rows on a conduit’s behalf, so a read is strictly less power than the write it already has. **The transform is still pure**: read-only, no source API, no credential, no write. `ctx.query` cannot mutate anything. **Exercise it offline, before you deploy.** `turbobase ext replay --fixture` runs a declared read against rows the fixture supplies — add a `queryRows` map keyed by the query string your transform passes — so you can watch what the conduit asked for and what came back on your own machine. Run it once with no rows and `--trace` prints the strings your conduit actually composed, which is how you discover the key without deploying anything — including when the empty answer makes the conduit stop, where the error is the trace’s last line and the strings sit above it. See [Replaying a conduit that reads](/extending/sandboxes-and-testing/#replaying-a-conduit-that-reads). Replay serves the rows; it does not re-check the declaration, so the refusals above are still the deployed conduit’s first word on a read you got wrong. ## Idempotency and the cycle budget [Section titled “Idempotency and the cycle budget”](#idempotency-and-the-cycle-budget) Two distinct loop defenses: * **`idempotencyKey`** — dedups a replayed source webhook so the same inbound event doesn’t bridge twice; it anchors the `conduit_event` audit row. Make it derive deterministically from the trigger (`':'`), not from wall-clock or random data — a weak key is exactly what `turbobase ext lint` flags. **On `after_save` and `after_delete`, omit it.** A record saved here has no external id, so `ctx.externalId` is the record’s own surrogate key — the same string for the record’s create and for every later edit of it. A key built from it therefore dedups a record’s *second save into its first*, and the conduit fires once in that record’s lifetime and never again. Leave `idempotencyKey` off and each save gets its own key, which is what makes two saves two runs. If you do need your own key on one of these events, put something that moves in it — a field from `ctx.change`, say — and not `ctx.externalId` alone. `turbobase ext lint` warns `lifetime-idempotency-key` for exactly this, and says nothing about a key on the two inbound events, where `ctx.externalId` is the right one. * **`cycleBudget`** (default 4) — a hard per-conduit max-hop fuse on top of the opposite-direction + idempotency guards. When a record bounces more than `cycleBudget` times (A→B→A→…), the conduit trips. The hop a record sits at is read off the `conduit_event` ledger rather than carried on the job: neither sync seam knows a record’s chain position, so a budget that trusted them counted every leg as a fresh chain and could never trip. The one exception is a conduit’s OWN write, which carries its position with it, because at the moment that save is recorded the run that made it is not yet on the ledger to be read. Authoring two conduits that bridge the same pair in opposite directions is the classic way to create a cycle; the budget bounds the blast radius. Extreme values (0, or a very large number) are lint warnings. * **The opposite-direction guard** recognises the return leg two ways: by the id the echo arrives under, and — for the window between the conduit writing the master and the write-back confirming the target’s id — by the master itself. Both correlations rest on the write-back stamping the binding with the id the target source minted, which is what makes a two-way pair safe to author at all. ## Conflict handling [Section titled “Conflict handling”](#conflict-handling) `conflictStrategy` decides what happens when a fanned-out write to a bound source is **rejected**: | Strategy | Behaviour | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merge` (default) | Keep the master value, mark the rejecting **binding** divergent, raise a sync failure (→ admin rollup + AI healing). The master is never reverted; divergence is a visible, healable per-binding state. | | `skip` | Drop the write, leave the binding untouched. | | `overwrite` | Force the master value onto every binding (last-writer-wins), no divergence tracking. | | `revert-on-reject` | Opt-in, audited: the master reverts when any bound source rejects. Never the default. | ## Scaffold, lint, and replay [Section titled “Scaffold, lint, and replay”](#scaffold-lint-and-replay) Scaffold a conduit with the CLI: ```sh turbobase ext new conduit --source shopify --record order --to netsuite \ --event after_canonicalize_inbound ``` Then iterate offline before deploying: ```sh turbobase ext lint conduits/shop2ns.order.ts # semantic foot-guns, offline turbobase ext replay conduits/shop2ns.order.ts --fixture samples/order.json --trace ``` `replay` drives the conduit through its full lifecycle — dispatch guards → `from.when` → `transform` → apply-branch → bindings — in dry-run against a JSON fixture (no DB, no network), and with `--trace` prints the per-stage trace. See [Sandboxes and testing](/extending/sandboxes-and-testing/). ## A conduit is one producer of bindings, not the only one [Section titled “A conduit is one producer of bindings, not the only one”](#a-conduit-is-one-producer-of-bindings-not-the-only-one) The fan-out a conduit relies on — one master row, one binding per source, `txn_source_link` — is not the conduit engine’s private machinery. **The write boundary produces bindings too**: an app that names several systems on `parent.source_system` when it creates a record gets one master and one binding per named system, with no conduit anywhere. The realtime listener fans a later edit out to every one of them exactly as it does for a conduit’s. Two consequences worth knowing while you author one: * **A master you fire on may already be bound**, by a create rather than by a bridge. `ctx.bindings` is where you see them — each entry is `{ source, externalId, role }`, so it tells you which systems hold a copy, which of those copies has landed upstream yet, and which one the record belongs to (`role: 'origin'`). It does not tell you what produced a binding, and a conduit should not branch on that: write your transform against the bindings that are there. * **Write a conduit when the two sides need a transform, a condition or an ordering** — a patch shaped per target, `from.when`, a sequence of targets with `awaitSource`. If all a customer wants is “this record exists in both of these systems and should stay in step”, the app can ask for that on the create and no conduit is needed. ## Inspecting and repairing bindings [Section titled “Inspecting and repairing bindings”](#inspecting-and-repairing-bindings) A conduit’s observable output at runtime is its **run ledger** and its **bindings**. Stream the ledger: ```sh turbobase logs --conduit shop2ns:order --follow ``` List `txn_source_link` bindings — filter to the ones that need attention, or re-enqueue a divergent write (an admin personal access token (PAT) is required): ```sh turbobase ext binding --status divergent turbobase ext binding --retry bnd_123 ``` A non-retryable binding returns 409; only divergent/blocked bindings can be retried. ## Watching your conduits [Section titled “Watching your conduits”](#watching-your-conduits) Every deployed conduit is listed on the **Conduits** tab of `/data/extensions`, whether or not it has run — a bridge you shipped an hour ago appears immediately, with a zero run count rather than not at all. Each row carries its run and failure counts and p95 commit latency over the last 14 days, and **View run trace** opens that conduit’s run ledger. Above the list, a runs-vs-failures chart plots the same window a day at a time, which is what answers “has this bridge been getting worse”. Picking a day on it narrows both the list and the trace drawer to that day’s runs. The Mechanic does **not** propose conduits unprompted the way it proposes hooks. Conduits are authored deliberately — by you with the SDK and CLI above, or by an assistant you ask, over the authoring MCP server below. ## Turning one off, and removing it [Section titled “Turning one off, and removing it”](#turning-one-off-and-removing-it) A deployed bridge is not permanent. Every armed row on the Conduits tab carries **Disable** and **Remove** beside View trace, and the same two acts are one command from a terminal: ```bash turbobase ext disable shop2ns:order # stop it, keep it turbobase ext enable shop2ns:order # start it again turbobase ext remove shop2ns:order # delete the definition ``` **Disable keeps the definition; Remove does not.** A disabled bridge stops being compiled on the next registry reload and carries no traffic, but its code, its route and its history are all still there — **Enable** puts it straight back, and its row reads `disabled` rather than `draft`, so it is never mistaken for a proposal waiting on a decision. Removing deletes the row instead; the bridge comes back only by deploying its definition again, under the same id. **Neither touches what the bridge already did.** Its run ledger, the bindings it created and every record it wrote into the target system stay exactly as they are. Turning a bridge off stops it writing — it does not undo what it wrote. A job already queued when you disable a bridge is not lost work in flight: it lands on the ledger as `skipped`, with `conduit not loaded` as the reason, and writes nothing. Both acts need an administrator, on either door — a browser session on the tab, or a PAT carrying `extensions:deploy` whose user is an admin at the moment of the call — and each writes one row to the [audit log](/tenant/audit-log/) naming who did it. A conduit your instance is operated with as a managed-service guardrail refuses both, and renders neither control. `ext remove` is not `ext proposals reject`. Rejecting a HOOK proposal is terminal: its id becomes the denylist entry that stops the Mechanic proposing the same rule again. A removed conduit id is simply gone, and redeploying it works. ## Asking the assistant to draft one [Section titled “Asking the assistant to draft one”](#asking-the-assistant-to-draft-one) `scaffold_conduit` hands back the right shape with the `transform` left empty. When you would rather describe the bridge than write it, `author_conduit` takes the sentence instead: > when a shopify order is paid, raise the matching NetSuite sales order Your tenant writes the module against the target record’s real columns, then checks it the same way a deploy would — it loads the result, validates it, and refuses an unwritable target **before** it drafts anything, with the same sentence [the deploy refusal](#the-target-must-be-writable) gives. What comes back is a **proposal, not a deployment**. It lands on the Conduits tab at `/data/extensions` with the checked source, and it carries no traffic until an administrator applies it — the same review step an [authored hook](/extending/writing-hooks/) passes through. Read the transform before you apply it: the bridge starts writing into the target system the moment you do. Drafting needs an AI provider configured for this instance and an administrator token; without one the tool answers that it is unavailable rather than producing an unchecked guess. Under the tool is `POST /v1/extensions/author-conduit`, which takes `{intent, from: {source, recordType}, to: {source, recordType}}` and answers `{status, intentId, id?, reason?}` — `written` staged a proposal, `rejected_by_validation` says why it could not. Like the rest of the `/v1/extensions` family it is the extension-authoring surface, reached with an admin [PAT](/tenant/access-tokens/) carrying `extensions:deploy`; it is not a route your apps call. ## Grounding over the authoring MCP [Section titled “Grounding over the authoring MCP”](#grounding-over-the-authoring-mcp) Authoring through an MCP client — Claude Code via [`turbobase mcp`](/cli/reference/#mcp), or the remote `/mcp/authoring` endpoint with a [PAT](/tenant/access-tokens/) carrying `mcp:authoring` — gets the same grounding hooks do, and conduits lean on it harder because a conduit must understand **both** ends of the bridge: * **Instructions** at `initialize` name your connected sources (the candidate `from`/`to` pairs), what’s already deployed, the loop — scaffold → `mock_test` until green → `deploy` with `approve: true` — and `author_conduit` as the alternative to starting from a blank template. * **Prompts** — connector skills for the connected sources via `prompts/list` / `prompts/get`: the record anatomy on each side of the transform. * **Resources** — `recipes:///` is the cross-source mapping aid: intent recipes (columns, stats, actions per record type + intent) filtered to your installed sources, so a `transform` knows which canonical fields carry the intent across. `catalog:///` and `types://all` give the canonical schema; the `samples:///` fixtures are what `mock_test` and `replay` run against. Only connector skills surface here; admin-authored skills for Pilot, your AI assistant in the app, never appear on the authoring server. ## Next steps [Section titled “Next steps”](#next-steps) * [Writing hooks](/extending/writing-hooks/) — the single-source counterpart. * [Sandboxes and testing](/extending/sandboxes-and-testing/) — `replay` + `lint` a conduit. * [Deploy, plan, promote](/extending/deploy-plan-promote/) — ship a conduit. # Writing hooks > Author hooks that validate and shape records on record lifecycle events with the defineHook contract. Shipped A **hook** is a TypeScript file that exports a `defineHook({...})` declaration. There are no “plugins” and no “customization rules” — one extension surface, one runtime that loads it. A hook intercepts a record on a single source’s write path (or a standalone record where Turbobase is the system of record) and either validates it, patches it, or logs against it. This page is the how-to: the `defineHook` contract, the lifecycle events, the execution model, and the proactive-learning **Mechanic** loop that proposes hooks for you. ## Install the SDK [Section titled “Install the SDK”](#install-the-sdk) The authoring SDK ships as the npm package **`@turbobase/extensions`**. Install it in your extensions working tree for local typechecking and editor completion: ```sh npm install --save-dev @turbobase/extensions ``` The root export carries the full public API: the `defineHook` / `defineConduit` factories and the generic `defineExtensionKind` machinery they build on, the publish-manifest validators (`ManifestSchema`, `validatePublishManifest`), and the `generateTypes` codegen library behind [`turbobase project types`](/cli/reference/#project-types). Subpath exports let you import one surface at a time: `@turbobase/extensions/hook`, `/conduit`, `/define`, and `/types-gen`. The package is pure and credentials-free, and installing it never touches your instance — at runtime the import resolves to the code sandbox’s inline stub, so your deployed bundle carries no npm dependency. ## The `defineHook` contract [Section titled “The defineHook contract”](#the-definehook-contract) `defineHook` is a pure identity factory that adds Zod validation and ergonomic types. The shape your default export must satisfy: ```ts import { defineHook } from '@turbobase/extensions'; export default defineHook({ id: 'custom:salesorder:require-subsidiary', // stable, unique; survives renames recordType: 'salesorder', // string | string[] | '*' event: 'before_save', // one of the 6 lifecycle events source: 'netsuite', // omit for cross-source / standalone when: (ctx) => ctx.tenantConfig.netsuite?.oneWorldEnabled === true, // optional gate failClosed: true, // optional; default fail-open description: 'subsidiary required on OneWorld accounts', run: (ctx) => { if (!ctx.payload.subsidiary) { ctx.reject({ code: 'MANDATORY_FIELD_MISSING', field: 'subsidiary', message: 'subsidiary required on OneWorld accounts', }); } }, }); ``` | Field | Required | Meaning | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | yes | Stable id. Collisions across files are loader errors. Convention: `::` for code-baseline, `custom:` or `mechanic::` otherwise. | | `recordType` | yes | The record type to bind to — a string, an array, or `'*'` for every record. | | `event` | yes | One of the 6 [lifecycle events](#the-six-lifecycle-events). | | `source` | no | Restrict to one source (`'netsuite'`); omit for cross-source; use `'standalone'` for standalone-only. | | `when` | no | Predicate gating execution before `run` fires; branch on `ctx.tenantConfig`, `ctx.direction`, etc. | | `run` | yes | The hook body. Receives `ctx`; calls `reject` / `patch` / `log`. | | `failClosed` | no | See [fail-open vs fail-closed](#fail-open-vs-fail-closed). Default fail-open. | | `timeoutMs` | no | Execution-budget override; default 200ms. | | `description` | no | Operator-friendly text surfaced in the UI. | | `systemReserved` | no | Managed-service guardrail instance admins can’t disable — see [system-reserved hooks](#system-reserved-hooks). Reserved for platform code. | Hooks are **pure and credentials-free**: `HookContext` has no `secrets`, and nothing in a hook reaches a token, env var, or the secrets backend. The runtime runs untrusted hooks inside an isolated-vm sandbox with no IO — see [Sandboxes and testing](/extending/sandboxes-and-testing/). ## The eight lifecycle events [Section titled “The eight lifecycle events”](#the-eight-lifecycle-events) ```ts // exported from @turbobase/extensions export const HOOK_EVENTS = [ 'before_read', 'before_save', 'after_save', 'before_delete', 'after_delete', 'before_sync', 'after_sync', 'on_sync_failure', ] as const; ``` Those eight are the events a hook can bind to. [Conduits](/extending/writing-conduits/) — “a hook that bridges sources” — bind to three of their own: `after_canonicalize_inbound`, `after_sync_success_outbound` and `after_save`. **The last name is in both lists and means two different things.** A hook’s `after_save` runs on the write path of the record being saved, synchronously with the save, for that one record type; a conduit’s fires after any save on the instance has COMMITTED, whoever made it, and its job is to drive another source. Use the hook to shape or validate the record, the conduit to react to it. `before_read`, `before_save`, `after_save`, `before_delete` and `after_delete` are **universal** (they fire for standalone records too); `before_sync`, `after_sync`, and `on_sync_failure` are **connector-only** (they fire only when a source connector is propagating the record). **Delete has its own pair, and that is deliberate.** A `before_save` rule never sees a delete, so a record whose writes are validated is not thereby protected from deletion — the rule that blocks deleting an order with a fulfillment has to bind to `before_delete`. Note the payload difference: a delete is addressed by key (`pg_row_id` / `external_id`), not by row body, because resolving the row is fused with the tombstone stamp in one transaction to close a read-then-stamp race. So `before_delete` can reject, but there is no row body to patch. | Event | When it fires | Typical use | Can `reject`? | Can `patch`? | | ----------------- | -------------------------------------------------------- | ------------------------------------------------------ | -------------- | ----------------- | | `before_read` | Before a record is read out | Redact / gate reads | yes | yes | | `before_save` | Before a write is committed | Validate, fill defaults | yes | yes | | `after_save` | After the write committed | Observe, derive side data | no (committed) | no-op | | `before_delete` | Before a delete is tombstoned (after the guardrail gate) | Block deletes that break referential or business rules | yes | no (key, not row) | | `after_delete` | After the tombstone stamped | Observe, cascade, annotate | no (committed) | no-op | | `before_sync` | Before an outbound write leaves for the source | Last-mile shaping for the source | yes | yes | | `after_sync` | After the source accepted the write | Observe, stamp lineage | no (committed) | no-op | | `on_sync_failure` | When the source rejected the write | Classify / annotate the failure | no | no | `ctx.direction` tells you which way the operation is flowing — `'outbound'` (propagating to the source), `'inbound'` (a source webhook applying to the canonical mirror), or `'standalone'` (no connected source). `ctx.origin` tells you what triggered it — `'user'`, `'agent'`, `'webhook'`, or `'system'`. ## The hook context — `reject`, `patch`, `log` [Section titled “The hook context — reject, patch, log”](#the-hook-context--reject-patch-log) `run(ctx)` receives a `HookContext`. The read surface includes `recordType`, `event`, `direction`, `origin`, `source`, `payload` (the working record — mutable via `patch`), `prior` (the previous payload on updates), `user`, `tenantConfig` (the source-feature snapshot), and `metadata` (source-specific scoping, e.g. NS `customFormId`). The three mutators: ```ts // Reject — short-circuits the pipeline. The rejection surfaces as a sync // failure with category='hook_validation' and the rejection code as classification. ctx.reject({ code: 'MANDATORY_FIELD_MISSING', field: 'subsidiary', message: '…' }); // Patch — mutate the working payload; subsequent hooks see the patched shape. // Multiple hooks patching the same field: last-writer-wins. ctx.patch({ memo: ctx.payload.memo ?? 'AUTO' }); // Log — structured logging, observable in hook_telemetry + the parse-error UI. ctx.log('warn', 'falling back to AUTO memo', { recordType: ctx.recordType }); ``` The first `reject` wins — the pipeline short-circuits, so a hook that rejects stops later hooks for that operation. ## Fail-open vs fail-closed [Section titled “Fail-open vs fail-closed”](#fail-open-vs-fail-closed) When a hook’s `run` throws an uncaught error, the default policy is **fail-open**: the runtime proceeds as if the hook didn’t run (the error is caught, isolated, and logged — one bad hook never wedges the queue). Set `failClosed: true` to stop the operation instead — appropriate for security-critical or contract-enforcing hooks where “couldn’t run” must mean “don’t proceed.” **A fail-closed hook that threw is not the same answer as `ctx.reject`.** It produced no verdict about the record, so the runtime does not report one. `ctx.reject` answers `422 { error: 'validation_failed' }` with your code, field and message; a throw — or an overrun of the `timeoutMs` budget — answers `503 { error: 'hook_unavailable' }` with a `Retry-After` header, and on the background sync queue it is retried on the job’s remaining attempts instead of failing the record permanently. Either way nothing is written. So a hook body that may fail for reasons of its own is honest about it: the caller is told to send the same record again, not to fix something. ## Where hooks live — the two trees [Section titled “Where hooks live — the two trees”](#where-hooks-live--the-two-trees) The loader scans hook files from two trees (it binds a hook by the `recordType` * `event` it **declares**, not by its path — the directory layout is purely organisational): 1. **`sources//hooks/**`** — code-baseline hooks shipped with the product. Reviewed first-party source (provenance `code-baseline`); these run in-process with IO. 2. **`custom/hooks/**`** — operator- and Mechanic-authored hooks, cross-source or standalone (provenance `operator` / `mechanic`). These are untrusted customer/AI-authored code: bundled and run in the isolated-vm sandbox. Per-source operator hooks may also live at `sources//custom/hooks/**` so they sit next to that source’s tree while still being operator-provenance. The `.proposed/` subtree under `custom/hooks/` is **skipped** — Mechanic proposals are inert until an operator confirms them. ## Worked example: code-baseline (Oracle NetSuite customer) [Section titled “Worked example: code-baseline (Oracle NetSuite customer)”](#worked-example-code-baseline-oracle-netsuite-customer) `sources/netsuite/hooks/customer/before_save.require-name.ts` enforces the NetSuite mandatory-name rule canonical-side, so a missing field surfaces at save time rather than after a wasted REST round-trip: ```ts export default defineHook({ id: 'ns:customer:require-name', recordType: 'customer', event: 'before_save', source: 'netsuite', description: 'Customer rows require either company_name (company) or first_name + last_name (individual). …', failClosed: true, run: (ctx) => { // `readIsPerson` / `readName` read the CANONICAL snake_case key first, then // the camelCase canonicalizer key, then `ctx.prior` — see below. const isPerson = readIsPerson(ctx); const companyName = readName(ctx, 'company_name', 'companyName'); const firstName = readName(ctx, 'first_name', 'firstName'); const lastName = readName(ctx, 'last_name', 'lastName'); // Individual customer: first + last both required. if (isPerson) { if (!firstName || !lastName) { ctx.reject({ code: 'MANDATORY_FIELD_MISSING', field: !firstName ? 'first_name' : 'last_name', message: 'Individual customers (is_person=true) require both first_name and last_name. …', }); } return; } // Company customer (default): company_name required. if (!companyName && !(firstName && lastName)) { ctx.reject({ code: 'MANDATORY_FIELD_MISSING', field: 'company_name', message: 'Customer requires company_name (or first_name + last_name …).', }); } }, }); ``` Note `failClosed: true` (a missing-name customer must never silently proceed), the `source: 'netsuite'` scoping, and that `run` only ever calls `ctx.reject` — it doesn’t reach out to NetSuite. ### Read the canonical (snake\_case) key first — and fall back to `ctx.prior` [Section titled “Read the canonical (snake\_case) key first — and fall back to ctx.prior”](#read-the-canonical-snake_case-key-first--and-fall-back-to-ctxprior) Two rules that a `before_save` hook gets wrong at the cost of rejecting every write, both learned the hard way (once on transactions, again on customer): **1. `before_save` payloads are snake\_case.** The event runs at the write boundary (`POST /v1/data/:recordType`), which hands hooks the canonical column names — `company_name`, not `companyName`. The camelCase spelling is the *canonicalizer’s* output shape and reaches a hook only on the inbound path of an adapter whose `trustInboundAdapter` is off. Read snake\_case first and treat camelCase as the fallback. A hook that reads only camelCase sees `undefined` forever, and with `failClosed: true` that is not a check that never fires — it is a check that rejects **everything**. **2. A partial PATCH does not restate fields it isn’t changing.** An edit that touches only `phone` carries no name key at all. Absent-because-unchanged and absent-because-never-set need opposite answers, so consult `ctx.prior` — the stored row as it was before this write — before rejecting. And key any classification flag (`is_person`) on **presence**, not truthiness: an explicit `false` is a real value, while a missing key must inherit from `prior` rather than defaulting. Neither mistake shows up in a test that drives the DB directly. `POST`ing through PostgREST runs no `before_save` hook at all, so a spec built that way passes while every real app write 422s. Cover the hook with a unit test that calls `hook.run(ctx)` directly on a snake\_case payload, asserting both the rejection and the pass — and, for a field like this one, the `prior`-inheriting case where the key is absent rather than falsy. ## Worked example — standalone custom table [Section titled “Worked example — standalone custom table”](#worked-example--standalone-custom-table) `custom/hooks/cr_example/before_save.required-fields.ts` is the template for a hook on a **customer-authored standalone table** (an instance where Turbobase is the system of record). The directory name `cr_example` is organisational; the binding is the declared `recordType`: ```ts export default defineHook({ // 'custom::' for customer-authored hooks. id: 'custom:example:required-fields', // The standalone table's slug. Change this when you copy the template; // '*' would bind to EVERY record — scope it to one table. recordType: 'example', event: 'before_save', // Standalone tables have no connected source, so don't pin `source`. description: 'Validation for the standalone "example" table — rejects a save when the required `title` field is empty. …', failClosed: true, run: (ctx) => { const title = asStr(ctx.payload.cf_sa_title); if (!title) { ctx.reject({ code: 'MANDATORY_FIELD_MISSING', field: 'cf_sa_title', message: 'The "title" field is required on the example table.', }); } }, }); ``` Copy this to `custom/hooks/cr_/`, set the `recordType` to your table’s slug, and write the validation body. Because the template’s slug (`example`) won’t match a real table, it’s inert until you copy and re-point it. ## Hot reload [Section titled “Hot reload”](#hot-reload) The runtime watches both hook trees with chokidar and reloads the registry on change — a new file, an edit, a rename, or an `.overrides.json` change — so a hook takes effect **without a redeploy**. Each file is esbuild-transpiled with mtime+content-hash caching; a single bad file is isolated (its parse error surfaces in the parse-errors UI) and never breaks the rest of the registry. To author against a live-feeling instance before deploying, use [`turbobase sandbox create`](/extending/sandboxes-and-testing/). ## Enabling and disabling hooks [Section titled “Enabling and disabling hooks”](#enabling-and-disabling-hooks) Operators toggle hooks from `/data/extensions`: * **Code-baseline hooks** (`sources//hooks/`) are disabled via `custom/hooks/.overrides.json` — the loader drops overridden ids. * **Operator hooks** under `custom/hooks/` are disabled by renaming the file to `*.ts.disabled` (the loader skips it). The watcher reloads on either change, so a toggle is immediate. ### System-reserved hooks [Section titled “System-reserved hooks”](#system-reserved-hooks) A hook marked `systemReserved: true` (e.g. `ns:bidirectional-readonly`) is a managed-service guardrail whose enforcement *is* the contract — the customer is the party being gated, so the hook isn’t theirs to remove. In **managed mode** (the standard control-plane-operated instance) the loader ignores any override, the UI shows a locked badge, and the disable action 403s; to change the capability, staff flip the gating feature flag. Reserve this flag for platform code only. ## The Mechanic loop Preview [Section titled “The Mechanic loop Preview”](#the-mechanic-loop-preview) The **Mechanic** is the proactive-learning loop: it watches clusters of sync failures that share a signature, proposes preventive hooks (written to `custom/hooks/.proposed/`), and surfaces them for an operator to accept. A proposal is inert until accepted (the loader skips `.proposed/`), at which point it loads through the identical path as any authored hook. The Mechanic loop is in **Preview**. ## Grounding over the authoring MCP [Section titled “Grounding over the authoring MCP”](#grounding-over-the-authoring-mcp) When you author through an MCP client — Claude Code via [`turbobase mcp`](/cli/reference/#mcp) over stdio, or any client pointed at the remote `/mcp/authoring` endpoint with a [personal access token (PAT)](/tenant/access-tokens/) carrying `mcp:authoring` — the server grounds the client before its first tool call: * **Instructions** at `initialize` name your connected sources, what’s already deployed, and the authoring loop: scaffold → `mock_test` until green → `deploy` with `approve: true`. * **Prompts** — the connector skills (record anatomy, domain playbooks) for the sources you have connected, via `prompts/list` / `prompts/get`. A skill for a source you don’t have never appears. * **Resources** — `catalog:///` and `types://all` for the schema a hook’s payload satisfies, `samples:///` for fixture rows, and `recipes:///` for the source-filtered intent recipes (which columns and actions matter for a record type + intent) — exactly the field knowledge a validating hook encodes. Only connector skills surface here; admin-authored skills for Pilot, your AI assistant in the app, never appear on the authoring server. ## Next steps [Section titled “Next steps”](#next-steps) * [Sandboxes and testing](/extending/sandboxes-and-testing/) — `turbobase ext test` / `lint` your hook before deploying. * [Deploy, plan, promote](/extending/deploy-plan-promote/) — ship a hook with `turbobase ext deploy`. * [Writing conduits](/extending/writing-conduits/) — the cross-source counterpart. * [CLI reference](/cli/reference/#ext-new-hook) — the `ext new hook` scaffolder. # Writing processes > Author processes — multi-record sequences an app invokes and the platform runs on the server, in order, with the source's verdict awaited and a rollback when a step fails — with the defineProcess contract. Shipped A **process** is the third extension kind, beside [hooks](/extending/writing-hooks/) and [conduits](/extending/writing-conduits/). A hook runs on one record’s write; a conduit fires when a record crosses a source boundary; a process is **asked for** by an app and runs a fixed sequence of record writes on the server: “raise a purchase order, wait until the source has posted it, then raise the bill against it.” The ordering, the waiting, the validation and the undo all happen on the server, survive a worker restart, and are reusable by every app on the instance — instead of living in one app’s browser code, where a closed tab or a locked phone loses the run mid-chain. It is authored with the same SDK, validated by the same Zod machinery, run in the same isolated-vm sandbox and stored in the same DB-native store as the other two kinds. The SDK is the same `@turbobase/extensions` package — see [Install the SDK](/extending/writing-hooks/#install-the-sdk) for local typechecking (`@turbobase/extensions/process` is the process-only subpath). ## The `defineProcess` contract [Section titled “The defineProcess contract”](#the-defineprocess-contract) ```ts import { defineProcess } from '@turbobase/extensions'; export default defineProcess({ id: 'acme:raise-po-and-bill', // the :id an app invokes input: { // JSON Schema — validated at invoke type: 'object', properties: { vendorId: { type: 'string' }, amount: { type: 'number' } }, required: ['vendorId', 'amount'], }, steps: [ { id: 'po', recordType: 'purchaseOrder', awaitSource: true, // hold the next step for the source's verdict build: (ctx) => ({ parent: { entity_id: ctx.input.vendorId } }), }, { id: 'bill', recordType: 'vendorBill', build: async (ctx) => { // a read, as the invoking user — exactly what POST /v1/batch does const [vendor] = await ctx.query(`entity?select=terms_id&entity_type=eq.vendor&external_id=eq.${ctx.input.vendorId}`); return { parent: { created_from_id: ctx.steps.po?.externalId, // the id the source minted for step one entity_id: ctx.input.vendorId, terms_id: vendor?.terms_id ?? null, }, }; }, }, ], onFailure: 'rollback', // undo what landed when a step fails }); ``` | Field | Required | Meaning | | --------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | yes | Stable id; collisions are loader errors. Convention `':'`. It is the `:id` in `POST /v1/processes/:id`. | | `input` | yes | A JSON-Schema **object** the invoke body is validated against. A body that fails it is refused with the field named, and no run is created. | | `steps` | yes | The ordered step list, at least one entry, ids unique. An entry is one **step**, or a **repeated group** of them — see [Repeating a group of steps](#repeating-a-group-of-steps). A step acts on **one** record of `recordType` through the boundary your app’s own writes cross: it creates one, [changes](#changing-a-record-instead-of-creating-one) one, or [removes](#removing-a-record) one. | | `steps[].awaitSource` | no | Hold the **next** step until the source has given its verdict on this one — `confirmed` with the minted id, or `failed` with the source’s own sentence. Declare it whenever a later step needs `ctx.steps..externalId`. | | `steps[].build` | yes, unless `delete` | Pure `ctx → { parent, lines? }` — the same payload `POST /v1/data/:recordType` takes — or `null` to decline this time. Nothing else is read from it: a `pgRowId` or `externalId` returned beside `parent` is ignored, and the step **creates**. To change an existing record, declare `update`. The engine performs the write; the step never does. A step that declares `delete` has nothing to build and must **not** carry one. | | `steps[].update` | no | Makes this step **change** a record instead of creating one. See [Changing a record](#changing-a-record-instead-of-creating-one). | | `steps[].delete` | no | Makes this step **remove** a record instead of writing one, and the step carries no `build`. See [Removing a record](#removing-a-record). | | `steps[].when` | no | `ctx → boolean`. `false` records the step `skipped` and the run carries on. See [A step that declines](#a-step-that-declines). | | `steps[].rollback` | no | `'undo'` (default) or `'keep'` — what a failure **at this step** does to what the run already created. See [Scoping the rollback](#scoping-the-rollback). A `delete` step is always `'keep'`. | | `steps[].onRefused` | no | **Delete steps only.** `'stop'` (default) or `'continue'` — whether a refused delete ends the run. See [What a refused delete does to the run](#what-a-refused-delete-does-to-the-run). Declaring it on any other step is refused at deploy time, because a refused write always ends the run. | | `eachRow` | no | Makes this a **migration**: the step list runs once per outstanding row, a slice at a time. See [Moving many records](#moving-many-records). | | `onFailure` | no | `'stop'` (default — what landed stays) or `'rollback'` (delete everything the run created, newest first). | | `description` | no | Operator-friendly text in the UI. | ## What a step can see [Section titled “What a step can see”](#what-a-step-can-see) `ctx` carries `input` (already validated), `runId`, `steps` — every earlier step’s `{ pgRowId, externalId, disposition }` keyed by step id — `row` (the source row this pass is migrating, for a process that declares `eachRow`), `item` and `index` (the element this iteration of a repeated group is for, and its position), `log(...)`, and **one** read, `ctx.query(q)`. The read takes a PostgREST path-and-query exactly like the client’s `select()` (`order?select=id,total&limit=100`) and runs **as the user who invoked the process**, carrying their session: a row their row-level security hides is absent from the result, and a process cannot widen its own read scope. There are no secrets in the context and no way to call a source system — a process is pure, like a conduit, and the engine does every write. **`ctx.query` cannot write, and three things stop it.** The request leaves as a GET; the path is one resource name, so no stored procedure can be named (PostgREST exposes those under `rpc/`, which the read refuses); and the session it carries is the invoking user’s, which holds no write grant of its own. A step changes a record by returning one from `build()` — the engine takes it through the write boundary, with the hooks, the guardrails and the audit trail that door runs. Reaching for a write through the read is not a shortcut past them; it is refused three times over. **A read works however long the run has been going.** The session `ctx.query` carries is renewed before it expires, so a step that reads an hour into a run — after a few `awaitSource` waits — reads as the first step did. It is still the invoking user’s session: if an administrator changes that user’s access while the run is going, the run’s later reads are refused rather than carried on under the old access. ## Changing a record instead of creating one [Section titled “Changing a record instead of creating one”](#changing-a-record-instead-of-creating-one) A step **creates** a record by default. Declare `update` and it changes one instead — which is what a linking pass needs, because the first half of a pair is created before the second half’s id exists: ```ts steps: [ { id: 'out', recordType: 'salesOrder', awaitSource: true, build: (ctx) => ({ parent: { … } }) }, { id: 'back', recordType: 'salesOrder', awaitSource: true, build: (ctx) => ({ parent: { … } }) }, { id: 'link', recordType: 'salesOrder', update: { step: 'out' }, // what an earlier step landed build: (ctx) => ({ parent: { paired_with_id: ctx.steps.back?.externalId } }), }, ] ``` Address the record one of three ways, and only `step` is a plain string — the other two are functions of the context, because a declaration cannot know the value until the run: | Key | Addresses | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `update.step` | What an earlier step of **this run** landed, by its id. Inside a repeated group that is the namespaced id, `'leg:2:doc'`. | | `update.pgRowId` | `(ctx) => string` — a row the run did not create, by its surrogate key. | | `update.externalId` | `(ctx) => string` — the same, by the id the source minted. | | `update.expectedSyncVersion` | `(ctx) => number` — optimistic concurrency. The row’s current version must match. | `build` is unchanged: it returns the payload, and only the fields it names are written. The write goes through the **same** boundary as a create, so your `before_save` hooks, guardrails, write RLS and the write trail all apply — and the refusal on the step’s ledger row is the boundary’s own. A row the invoking user cannot see is a `404`; a moved `expectedSyncVersion` is a `409`. An address that resolves to nothing — a `step` that was skipped or has not run, or a `pgRowId` function that returned `undefined` — **fails the step** with `STEP_ADDRESS_UNRESOLVED`, naming what it could not resolve. It is never allowed to fall through to a create: that would quietly make the record the update was meant to change, with nothing downstream able to tell. **The address lives on `update`, never in what `build` returns.** A step that returns `{ pgRowId, parent }` from `build` and declares no `update` is a **create** — the extra key is not read — and it inserts a new row every time it runs. `recordType` must be the record type of the row you address; the boundary looks the row up in that type’s table. **If an update step still creates rows, the code that ran is not the code you wrote.** Check the two things that cause it, in order: the instance is older than **v1.38.0** (where `update` first shipped — an older instance drops the key at deploy and the step creates), or an older deployed copy of the process is still the one being served — see [Deploying a new version](#deploying-a-new-version). ## Removing a record [Section titled “Removing a record”](#removing-a-record) Declare `delete` and the step **removes** a record instead of writing one. It carries no `build` — a delete has nothing to build — and it addresses records your run did not create, which is what a background cleanup needs: undoing a migration, clearing a batch an import got wrong. Your app declares the work once and the platform runs it, so it survives the page being closed. ```ts steps: [ { id: 'drop-invoice', recordType: 'invoice', delete: { externalId: (ctx) => ctx.input.invoiceId, // the id the source minted sourceSystem: 'netsuite', }, onRefused: 'continue', }, ] ``` Address the record one of two ways — the same two keys `DELETE /v1/data/:recordType` takes, and both functions of the context for the reason an `update` address is: | Key | Addresses | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `delete.pgRowId` | `(ctx) => string` — the row by its surrogate key. | | `delete.externalId` | `(ctx) => string` — the row by the id the source minted. | | `delete.sourceSystem` | Which system the record belongs to. A **qualifier**: it narrows which table the id is looked up in on an instance where one record type means different things under two connected systems. It never decides where the delete is sent — the row’s own system does that. | There is deliberately no `delete.step`. A step addresses a record the run did **not** create; a run that deleted its own work is a rollback, which is what `onFailure: 'rollback'` is for. **It is an ordinary delete.** The step crosses the same boundary your app’s own `DELETE /v1/data/:recordType` crosses, as the user who invoked the run — so write RLS, the write-back entitlement, the `.delete` guardrail and your `before_delete` and `after_delete` hooks all apply exactly as they do to a delete your app sends, and the refusal on the step’s ledger row is theirs. It is charged to your instance’s ordinary **delete** cap. **A delete cannot be undone**, so the step is always `rollback: 'keep'`: declaring `rollback: 'undo'` is refused at deploy time, and a rollback some other step causes passes over it. The records it removed stay removed. ### What a refused delete does to the run [Section titled “What a refused delete does to the run”](#what-a-refused-delete-does-to-the-run) `onRefused` decides, and it is the one choice this step asks you to make: | Value | The run | | ------------------ | ---------------------------------------------------------------------------------------- | | `'stop'` (default) | Ends at the refusal, as every other step does. The remaining steps are `skipped`. | | `'continue'` | Carries on to the next step and commits. The refusal is still on this step’s ledger row. | Reach for `'continue'` on a tier-ordered cleanup — transactions, then entities, then items. A record the connected system will not delete because another document still points at it is a record to **leave alone**, not a reason to abandon the remaining tiers. Either way the outcome of every record is on the run’s step ledger. Read it with `GET /v1/processes/runs/:runId`, which answers one entry per step in the shape [Watching a run](#watching-a-run) sets out: * `disposition` — `confirmed` for a record that is gone, `failed` for one that was refused, `skipped` for a step that was never attempted: its `when` declined, an earlier step failed, or the run paused on the delete cap with steps still to go. * `refusal` — `null`, or `{ code, field, message }`: the refusal’s own code and sentence, whichever party refused — your guardrail, a hook, or the connected system. * `pgRowId` and `externalId` — which record the step removed. **Read `refusal` on a `confirmed` entry too**, because there is one `confirmed` that does not mean the record is gone from the connected system — the held delete below. Its `refusal.code` is `SOURCE_AWAITING_CONFIRMATION`, and every other `confirmed` leaves `refusal` null. Those are the route’s names. The same rows are also readable through PostgREST as `process_run_step`, where the ledger’s own columns carry the same facts: `disposition`, `refusal_code`, `refusal_field`, `refusal_message`, `pg_row_id` and `external_id`. Reach for the table when you are already querying your data; reach for the route when you are watching one run. A delete the connected system refuses is **un-hidden again**: the record comes back and the step row explains why. An address that resolves to nothing fails the step with `STEP_ADDRESS_UNRESOLVED` and deletes nothing — it is never allowed to fall through. ### Pacing, and your delete cap [Section titled “Pacing, and your delete cap”](#pacing-and-your-delete-cap) Deletes are capped tighter than updates, because the cap is a circuit-breaker against a mass delete and a background run is exactly the thing that would trip one. A delete step **waits** for the rolling window to free and carries on in the same run, so you do not have to spread a cleanup thin to stay under it. A step still waiting when its budget runs out stops the run with the cap named on it, having deleted nothing at that step. That step and the ones after it are recorded `skipped`. Invoke the process again to carry on, or raise the cap in **Settings → Write guardrails**. ### A delete your instance holds for approval [Section titled “A delete your instance holds for approval”](#a-delete-your-instance-holds-for-approval) **This is the default, not an edge case.** Turbobase classifies a delete as destructive and asks an operator to approve it unless a guardrail rule on your instance says otherwise — so on a stock instance every delete a process makes is held, exactly as every delete your app sends is. A hold is **not a refusal**. The record is hidden in Turbobase straight away, the delete is queued, the run carries on to the next step and commits, and a person approves it on **Compliance → Guardrails** — the same path a delete your app sends takes. The step does not wait for that approval: nothing bounds how long a person takes. What tells you it happened is the step’s entry: | | `disposition` | `refusal` | | -------------------------------------------------- | ------------- | -------------------------------------- | | Removed, and the connected system has done it | `confirmed` | `null` | | Hidden here, waiting for an operator to approve it | `confirmed` | `code: 'SOURCE_AWAITING_CONFIRMATION'` | | Refused | `failed` | the refusing party’s own `code` | If your cleanup is meant to run unattended, write a rule for the record types it deletes — `allow_with_audit` on `.delete` keeps the audit trail and removes the hold. ## Repeating a group of steps [Section titled “Repeating a group of steps”](#repeating-a-group-of-steps) A step-list entry may carry nested `steps` instead of a `recordType` and a `build`. Declare `forEach` on it and the group runs once per element of an array read off the validated input: ```ts input: { type: 'object', properties: { legs: { type: 'array', items: { type: 'object' } } }, required: ['legs'], }, steps: [ { id: 'leg', forEach: { input: 'legs' }, // names a property of `input` steps: [ { id: 'doc', recordType: 'salesOrder', build: (ctx) => ({ parent: { memo: `leg ${ctx.index}`, entity_id: ctx.item.vendorId } }) }, { id: 'note', recordType: 'salesOrder', build: (ctx) => ({ parent: { created_from_id: ctx.steps[`leg:${ctx.index}:doc`]?.externalId } }) }, ], }, { id: 'close', recordType: 'salesOrder', update: { step: 'leg:0:doc' }, // address one iteration from outside the loop build: (ctx) => ({ parent: { memo: 'chain closed' } }), }, ] ``` * **`ctx.item` is the element and `ctx.index` its position**, from 0. * **Every iteration’s steps get their own ledger rows**, named `::` — `leg:0:doc`, `leg:0:note`, `leg:1:doc`, … That id is part of the contract you write against: it is how a later step reads one iteration’s outcome out of `ctx.steps`, and how it addresses one with `update: { step: … }`. * **`forEach.input` names a property rather than taking a function.** That is what lets the instance check the expansion against its cap before any of your code runs and before the first write. One run may repeat a group at most **100** times (`DEFAULT_PROCESS_FOR_EACH_MAX_ITEMS`). Over that, the run is refused with both numbers in its `reason` and **nothing is written** — a chain that wants hundreds of legs wants [`eachRow`](#moving-many-records), which the platform paces a slice at a time. ## A step that declines [Section titled “A step that declines”](#a-step-that-declines) Two ways, one outcome. `when(ctx)` says “not this time” before the payload is built; a `build` that returns `null` says it after: ```ts { id: 'rush', recordType: 'salesOrder', when: (ctx) => ctx.input.express === true, build: … }, { id: 'fee', recordType: 'salesOrder', build: (ctx) => (ctx.input.fee ? { parent: { … } } : null) }, ``` Either way the step is recorded **`skipped`** with no refusal on its row, the steps after it still run, and the run ends `committed`. Declining is not a refusal: a chain with an optional leg is a chain that succeeded. A `when` that **throws** is a different thing — an author whose condition is broken, not an author saying no — so it fails the step and stops the run rather than being read as a `false` that would silently drop a leg. ## Scoping the rollback [Section titled “Scoping the rollback”](#scoping-the-rollback) `onFailure` is the run’s switch; `steps[].rollback` narrows it to the step: ```ts onFailure: 'rollback', steps: [ { id: 'out', recordType: 'salesOrder', build: … }, // 'undo' — the default { id: 'back', recordType: 'salesOrder', build: … }, { id: 'stamp', recordType: 'salesOrder', rollback: 'keep', build: … }, // the closing stamp ] ``` **It is the failing step’s setting that decides whether the run rolls back at all.** A failure at `stamp` above undoes nothing and the run ends `failed`, so a closing stamp that could not be written does not destroy the chain it was closing. A failure at `out` or `back` rolls the run back exactly as it always has, and `stamp`’s own record is spared there too — `keep` is about this step’s record as well as about the run’s ending. Rolling a finished run back on request — `POST /v1/processes/runs/:runId/rollback`, see [Stopping work](#stopping-work) — is somebody asking rather than a failure, so the failing step’s `keep` does not stop it. Each step’s own `keep` still spares that step’s record. A record an **`update`** step merely changed is never deleted by a rollback and never put back: the run did not create it, the prior values are not the run’s to own, and restoring them would silently overwrite an edit somebody else made in between. The ledger is what says which steps changed what. `ctx.query` answers with the **whole** result set, or it throws. There is no row cap on it, and that is deliberate: a step reads in order to decide what to write, so a silently shortened answer would be a wrong write rather than a slow one. The `POST /v1/batch` row cap does **not** apply here. What does apply is a size ceiling — a single read whose response exceeds the per-read byte budget fails the step with the limit named, rather than coming back short. Ask for a page explicitly (`?limit=…&offset=…`) when a page is what you want, and prefer a filter to reading a table and narrowing it in `build`. Two **time** bounds apply as well. A read that has started is abandoned at the per-read ceiling. And reads take from a small pool of slots shared with the other runs on the same worker, so a read that waits too long for a slot is never sent at all. That second bound is the **worker’s own**, and it is several times longer than the one a request from an app gets: nobody is watching a background run, so it is given room to be slow, and the bound is there to end a run that is waiting on a queue that has stopped moving rather than to hurry one along. Either bound fails the step by name, with the bound that stopped it in the message, rather than waiting indefinitely — and a failed step ends the run (`failed`, or rolled back where the process asks for that), so the remedy is to invoke it again rather than to wait. One more reason to filter a read rather than drain a table: a step that reads everything holds a slot for as long as it takes, and the runs behind it are the ones that pay. ## Invoking a process [Section titled “Invoking a process”](#invoking-a-process) An app calls the process under its ordinary session — the same cookie its own writes use — with the input as the body. **The body *is* the input**, with no `{ input: … }` envelope around it: ```ts const res = await fetch('/v1/processes/acme:raise-po-and-bill', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ vendorId: '123', amount: 250 }), }); // 202 { runId, processId, state: 'queued' } ``` The response comes back **before the first step is written**. Nothing runs on the request: the run is queued, and a worker performs it. Refusals carry an envelope and never a `runId`: | Status | Body | Meaning | | ------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `401` | `{ error }` | No session. | | `404` | `{ error: 'process_not_found', id }` | No deployed process of that id. | | `400` | `{ error: 'invalid_input', rejection: { code, field, message } }` | The body fails the process’s `input` schema; `field` names what to fix. | | `400` | `{ error: 'invalid_mode', rejection }` | `?mode` was neither `sync` nor `async`. | | `409` | `{ error: 'process_disabled', id, reason }` | An administrator switched this process, or every process on the instance, off. See [Stopping work](#stopping-work). | | `202` | `{ runId, processId, state: 'queued' }` | Queued. | **Send the input bare.** A caller that posts `{ "input": { "batch": 7 } }` gets exactly that as `ctx.input` — `ctx.input.input.batch` — and `eachRow.outstanding` receives the same wrapped object. If one of your callers wraps the body and another does not, the process sees two shapes. An `input` schema with `additionalProperties: false` and the real properties `required` turns the wrapped shape into a `400` instead. **Who can invoke.** A signed-in session — an app, or a person in the browser — or a personal access token carrying `extensions:deploy` whose owner is an administrator, which is what `turbobase processes invoke` sends (see [From a terminal](#from-a-terminal)). A token’s run is its owner’s: it writes as that person, exactly as their browser session would. A token owned by anyone else is refused (`403 admin_required`). A process cannot start another process — a step has no network and no way to call the platform. For work that must carry on with nobody signed in, see [Keeping a long run going](#keeping-a-long-run-going). ### Waiting for the answer [Section titled “Waiting for the answer”](#waiting-for-the-answer) Add `?mode=sync` when the app wants the outcome rather than a ticket — a short chain a person is watching a spinner for: ```ts const res = await fetch('/v1/processes/acme:raise-po-and-bill?mode=sync', { … }); // 200 { runId, processId, state: 'committed', reason: null, outstanding: 0, steps: [ … ] } ``` The run itself is queued and performed by a worker exactly as an asynchronous one is — the same queue, the same engine, the same ledger. All that changes is that the request stays open until the run settles, and it is bounded: a run that outlasts the instance’s synchronous budget answers `202 { error: 'sync_budget_exceeded', runId, processId, state: 'queued', message }`. **That is not a failure and the run is not cancelled** — it is still going, which is why the answer carries its id. Watch it as below, or invoke it asynchronously in the first place. So in `?mode=sync` a `202` is the one answer that does not mean “finished”: **branch on `error`, not on the status.** A `200` carries the settled run, a `202` carries `error: 'sync_budget_exceeded'` and a run still going, and the `4xx` refusals above carry no `runId` at all. The two modes run in separate lanes with separate limits, so a long migration cannot crowd out the short interactive runs. ## Watching a run [Section titled “Watching a run”](#watching-a-run) Poll `GET /v1/processes/runs/:runId` under the same session. It answers the run — `state` is `queued` → `running` → `committed` | `failed` | `rolled_back` | `cancelled`, with a `reason` on any ending that needs one — and one entry per step: ```json { "run": { "runId": "…", "processId": "acme:raise-po-and-bill", "state": "committed", "reason": null, "outstanding": 0, "…": "…" }, "steps": [ { "sequence": 1, "stepId": "po", "recordType": "purchaseOrder", "pgRowId": "…", "externalId": "PO-1041", "disposition": "confirmed", "rowKey": "", "slice": 1, "refusal": null }, { "sequence": 2, "stepId": "bill", "recordType": "vendorBill", "pgRowId": "…", "externalId": null, "disposition": "confirmed", "rowKey": "", "slice": 1, "refusal": null } ] } ``` `rowKey` and `slice` matter for an `eachRow` migration: `rowKey` is the source row the entry belongs to, and `slice` is the slice of the run that recorded it. A row that a later slice offers again gets a second set of entries, one per visit. For a chain they are always `""` and `1`. A step’s `disposition` is one of `confirmed`, `failed`, `skipped` (it was never attempted — its `when` declined, an earlier step failed, or the run paused on the delete cap) or `rolled_back`. A step that was refused carries the refusing party’s **own** `code`, `field` and `message` — a `before_save` hook’s rejection, the write boundary’s, or the source’s sentence from the write trail — so a failed run explains itself the way a `422` from `POST /v1/data` does. The refusal stays on the row when a rollback later undoes that step’s record, so a `rolled_back` step can still say why. The same rows are readable through PostgREST as `process_run` and `process_run_step`, scoped by row-level security to the invoking user (an administrator sees every run). **`committed` does not always mean there is nothing left to do.** A run carries an `outstanding` count — the work it did not get to — and a slice of a migration ends `committed` with a non-zero one. You do **not** have to ask for the next slice: the run queues it itself, under the same run id, until nothing is outstanding or it reaches its slice cap. A run that stopped at the cap ends `committed` with a `reason` naming it, which is how “stopped early” and “finished” stay two different things to read. ## Watching the whole queue [Section titled “Watching the whole queue”](#watching-the-whole-queue) One run at a time is the wrong shape once a migration is thousands of records. `GET /v1/processes/queue` answers everything in one read, scoped exactly as the single-run read is: ```json { "runs": [ { "runId": "…", "processId": "acme:migrate-customers", "mode": "async", "state": "committed", "outstanding": 4, "failure": null }, { "runId": "…", "processId": "acme:migrate-customers", "mode": "async", "state": "failed", "failure": { "stepId": "customer", "code": "MANDATORY_FIELD_MISSING", "message": "company_name is required" } } ], "counts": { "queued": 12, "running": 2, "committed": 40, "failed": 1, "rolled_back": 0, "cancelled": 0 } } ``` Add `?mode=async` for the migration lane alone. Each failure travels **with** the run it belongs to, so nothing has to be looked up separately, and every bucket is reported even when it is empty — so “none cancelled” reads differently from “cancellation is not reported”. ## Stopping work [Section titled “Stopping work”](#stopping-work) ```ts await fetch('/v1/processes/acme:migrate-customers/cancel', { method: 'POST' }); // { cancelled: 387 } await fetch(`/v1/processes/runs/${runId}/cancel`, { method: 'POST' }); // { runId, state: 'cancelled' } await fetch(`/v1/processes/runs/${runId}/rollback`, { method: 'POST' }); // 202 { runId, state, queued: true } ``` The first stops every **queued** run of one process in a single call — a caller who queued four hundred slices is not asked for four hundred requests. The second stops one run, queued or running. A queued run never executes. A running one stops at its **next boundary** — the next step, and for a migration the next **row**, so a one-step migration stops after the row it is on rather than running to the end of its slice. The write in flight finishes rather than being killed halfway through, and **records already sent upstream stay** — even when the process declares `onFailure: 'rollback'`. A cancel is not a failure, and undoing records the source has already accepted is exactly the half-built chain rollback exists to prevent. A cancelled slice reports the rows it never started in `outstanding`, the same way one stopped by the budget does. Cancelling one slice cancels the run: a cancelled run queues no continuation. **To undo a run after it has stopped, roll it back.** The third call above deletes, newest first, the records the run’s ledger shows it created — the same records an `onFailure: 'rollback'` would have deleted, so a record an `update` step changed, a row an earlier run had already migrated and a step declared `rollback: 'keep'` are left alone. It works on a run that is `committed`, `failed` or `cancelled`; a run still `queued` or `running` answers `409` (cancel it first), and one already `rolled_back` answers `200` with `queued: false`. It is open to whoever invoked the run and to an administrator, and the deletes are made as the person who invoked it, through the same delete rules and hooks as any other delete. The work is queued rather than done inside the request, so the answer is `202`; watch the run until it reads `rolled_back` (or `failed`, with the records it could not remove named in its `reason`). **An administrator can also stop a process without touching its runs.** Switch one process off, or every process on the instance off, and no new run starts by schedule or by hand — an invoke answers `409` naming the switch — while a run already going stops at its next step boundary. A run also stops there when it passes the instance’s maximum runtime or maximum writes for one run. Every one of those endings is `committed` with a `reason` naming the limit or the switch, rather than `failed` — they are not faults, and counting them as failures would set off the alarms that watch for real ones. **Those two ceilings are the RUN’s, and they apply even where nobody has set one.** An instance that has never been told a number gets shipped defaults sized off the slice budget — the most work the slice caps already allow one run to do — so nothing that was going to finish is stopped by them, and a run that is stuck is bounded rather than endless. They count across the whole run, not per slice: a migration of a thousand slices has one runtime allowance and one write allowance between them, which is what “per run” means on an instance’s settings page. ## Carrying a stopped run on [Section titled “Carrying a stopped run on”](#carrying-a-stopped-run-on) ```ts await fetch(`/v1/processes/runs/${runId}/resume`, { method: 'POST' }); // 202 { runId, state, queued: true } ``` A run that stopped on an `awaitSource` wait is **resumed**, not started again. The same run goes back on the queue at the step it stopped on: every step its ledger already recorded is passed over, the one whose verdict never arrived is waited for again, and the rest of the chain runs. Nothing is written twice, because each step’s idempotency key comes from the run id and the run id does not change — which is exactly what invoking the process a second time cannot give you, since a new run’s keys are its own and its first steps create again. **A step that already said no is not asked again.** “Already recorded” covers a step whose `when` declined as well as one that wrote: the run reached it and decided, so the continuation leaves that decision alone even where the data the `when` read has changed in the meantime. Only the steps the run never reached are performed. If you want a declined step reconsidered against today’s data, invoke the process again rather than resuming the old run. **Only a run that stopped with work left.** `committed` with `outstanding` above zero is the one state a resume is for. A run still `queued` or `running` has not stopped, a `failed` or `rolled_back` one needs its refused step re-keyed rather than re-offered, a `cancelled` one was stopped by a person, and a `committed` run with nothing outstanding has finished — each answers `409` (`process_run_not_resumable`) naming the state on the body, with nothing queued. Two resumes in quick succession start one continuation; the second answers `409`. **A migration is invoked again instead.** An `eachRow` process keys each write by the source row, so a slice that stopped at its cap carries on by being invoked again — re-offering the same slice would be wrong rather than merely unnecessary. The resume answers `409 process_is_a_migration` and says so. It is open to whoever invoked the run and to an administrator, the continuation runs as the person who invoked it, and the work is queued rather than done inside the request — so the answer is `202`; watch the run until it reads `committed` with `outstanding: 0`. **The clock stays the run’s**: `startedAt` is not reset, so a resume cannot buy a run more than the instance’s maximum runtime, and a run already past it stops again at its first step boundary with the ceiling named in its `reason`. ## From a terminal [Section titled “From a terminal”](#from-a-terminal) ```sh turbobase processes list # what is deployed, and how it fires turbobase processes runs acme:migrate-customers # that process's whole history turbobase processes run 1111… # one run and its step ledger turbobase processes invoke acme:migrate-customers --input '{"batch":"2026-10"}' # start one, queued turbobase processes invoke acme:raise-po-and-bill --input-file po.json --sync # start one and wait turbobase processes cancel 1111… # stop it turbobase processes resume 1111… # carry on a run that stopped on a wait turbobase processes rollback 1111… # undo what a finished run created turbobase logs --process-run 1111… --follow # watch one run until it finishes ``` `processes invoke` sends the input — a JSON object, from `--input` or `--input-file` — as the whole request body, exactly as an app does. Queued, it prints the run id and the `logs --process-run` line to follow it; with `--sync` it prints the settled state, anything outstanding and each step, or — past the instance’s budget — that the run is still going and how to watch it. `processes list` is the read behind the admin **Processes** screen as well: every deployed process with its trigger — `manual`, or `scheduled` with **both** the cron expression and the timezone it is read in — whether it is switched on, and its last five runs. It is scoped by your own row-level security, so the processes are everyone’s and the runs are yours (an administrator sees every run). Following a run is a flag on the one log verb rather than a `processes logs` of its own, because all log access on this CLI unifies under `turbobase logs`. Unlike `--conduit`, it **ends**: a run reaches a terminal state, so `--follow` returns there instead of polling until you interrupt it. ## Moving many records [Section titled “Moving many records”](#moving-many-records) A process runs its step list once, which is the right shape for a three-record chain and the wrong one for moving tens of thousands of records. Declare `eachRow` and one invocation becomes a **slice** of that work: ```ts export default defineProcess({ id: 'acme:migrate-customers', input: { type: 'object' }, eachRow: { // Re-run at the start of EVERY slice. Write the predicate that excludes // what is already done, and rows an earlier slice finished simply are not // in the answer any more. outstanding: () => 'legacy_customer?select=id,company_name&migrated_at=is.null&order=id', key: 'id', }, steps: [ { id: 'customer', recordType: 'customer', build: (ctx) => ({ parent: { company_name: ctx.row!.company_name } }), }, ], }); ``` * **`outstanding`** returns one PostgREST query — the same shape `ctx.query` takes — read as the invoking user and row-level-security-scoped for free. * **`key`** names the column that identifies a row. That value becomes the write’s idempotency key, which is what makes re-offering a row a **no-op** rather than a second record upstream. Without it every retry of a slice would duplicate everything it had already moved. * **Each step reads its row from `ctx.row`**, not from `input`: `input` describes the whole migration, the row describes one record of it. One invocation takes rows off the front of that answer until the instance’s slice budget — a record count or a wall clock, whichever comes first — stops it. It finishes the step it is on, ends `committed` with the remainder in `outstanding`, **and queues the next slice itself**. One run id, one ledger, several deliveries: you invoke a migration once and it carries on until nothing is outstanding. A separate job each time rather than a loop, deliberately — a loop would hold its lane for the whole migration, which is the starvation the two-lane design exists to prevent. The chain is bounded by a per-run slice cap, so a migration that is larger than anyone expected stops and says so rather than running forever. Re-offering a row is still safe, which is why the `key` above matters: a create step offered the same row twice writes it once. An update step does not work that way. It runs again on every visit, so the row can move through states over several slices (see the contract below). ### The `eachRow` contract [Section titled “The eachRow contract”](#the-eachrow-contract) * **`outstanding(input)` receives the bare invoke body** — the same object as `ctx.input` — and returns one PostgREST query. * **It is read once per slice, not once per row.** The slice works through the rows that one read returned. A row that becomes outstanding while the slice is running is not in that answer; the next slice’s read picks it up. If the slice finished every row it read, nothing is outstanding and the run ends — a row added during that last slice waits for the next invocation or schedule. * **`outstanding` on the run is counted from that read**: the rows the slice read minus the rows it finished. * **Your predicate must exclude a row once it is done.** That is what makes a slice’s work shrink. A predicate that keeps returning finished rows makes every slice re-offer them, and the run keeps re-queuing until it reaches its slice cap. The usual shape is an update step at the end of the list that stamps the row out of the predicate. See the [migration recipe](#a-migration-recipe). * **Each time a later slice or a later run offers a row again, that is a new visit.** On that visit: * **Create steps run once per row `key`.** The step records `skipped` and hands `ctx.steps` the record that was created first, with its `pgRowId` and `externalId`, so later steps can still address it. * **Update steps run again on a later visit.** Their write goes through the boundary again, so a row can be stamped `sent` on one visit and `recorded` on a later one. * **A step that declined runs its `when` and `build` again.** That covers a `when` that returned false and a `build` that returned `null`. A step that declines while the row is waiting acts on the visit where it is ready. * **An AI step reuses its answer for the rest of the run.** Once the model has answered for a row, later slices of the same run hand that answer on as `skipped` and do not bill again. A new run asks the model again. * **A crash re-delivery is not a new visit.** If a worker dies mid-slice, the queue hands the same slice back. That delivery resumes after every step the slice already recorded, whether `confirmed` or `skipped`, and writes nothing twice. A row the outstanding read lists twice in one slice is also visited only once. * **Steps share state only through `ctx.steps` and `ctx.row`.** `ctx.steps` holds the outcomes of earlier steps **for the row being processed** and starts empty for the next row. There is no memory across rows or slices: anything a later row needs to know belongs in a table the steps write and `ctx.query` reads. * **A step that fails on one row ends the run** under `onFailure`, the same as in a chain. The rows after it are counted in `outstanding`. | Limit | Default | Set by | | ---------------------------- | ------------------------------------------- | --------------------------------------- | | Rows one slice works through | 500 (`DEFAULT_PROCESS_SLICE_MAX_ROWS`) | the instance (`PROCESS_SLICE_MAX_ROWS`) | | Wall clock one slice may run | 10 minutes (`DEFAULT_PROCESS_SLICE_MAX_MS`) | the instance (`PROCESS_SLICE_MAX_MS`) | | Slices one run may take | 1000 (`DEFAULT_PROCESS_MAX_SLICES`) | the instance (`processes.slice_cap`) | A slice checks both of its limits before **starting** a row, never in the middle of one. ### A migration recipe [Section titled “A migration recipe”](#a-migration-recipe) The common shape is a tracking table your app owns — one row per record to move, with a status — and a process that creates the target record for each pending row and then marks that same row done. Everything below needs an instance on **v1.38.0 or later**: `update` steps, `ctx.row` inside a deployed process, slices that queue themselves and `{ kind: 'process' }` schedules all first shipped there. ```ts import { defineProcess } from '@turbobase/extensions'; export default defineProcess({ // Keep this the FIRST `id:` in the file — see "Deploying a new version". id: 'acme:migrate-customers-tracked', input: { type: 'object', properties: { batch: { type: 'string' } }, additionalProperties: false }, eachRow: { // Select pg_row_id: the update step below addresses the row by it. outstanding: (input) => `migration_item?select=pg_row_id,legacy_id,company_name&status=eq.pending&batch=eq.${input.batch}&order=legacy_id`, key: 'legacy_id', }, steps: [ { id: 'create', recordType: 'customer', build: (ctx) => ({ parent: { company_name: ctx.row!.company_name } }), }, { id: 'mark', recordType: 'migration_item', // the record type of the row you change update: { pgRowId: (ctx) => ctx.row!.pg_row_id as string }, rollback: 'keep', build: (ctx) => ({ parent: { status: 'sent', target_pg_row_id: ctx.steps.create?.pgRowId ?? null }, }), }, ], }); ``` * `mark` **changes** the row this pass is on. It does not insert, because it declares `update`, and it takes the row out of `outstanding` because it moves `status` off `pending`. * `create` does not declare `awaitSource`, so `mark` records the new row’s `pgRowId` — set the moment the write lands — rather than waiting for the connected system to mint its id. In bulk, a wait for the source’s verdict runs out behind the queue of other writes; read the verdict later from the new row (`synced_at`, `external_id`) or the write trail. * `pg_row_id` is in the `select`. Leave it out and `ctx.row.pg_row_id` is `undefined`, and `mark` fails with `STEP_ADDRESS_UNRESOLVED`. * `rollback: 'keep'` on the stamp means a failure while stamping does not undo the record `create` already made upstream. * Invoke it once — `POST /v1/processes/acme:migrate-customers-tracked` with `{ "batch": "2026-10" }` — and it carries on by itself. ### Keeping a long run going [Section titled “Keeping a long run going”](#keeping-a-long-run-going) You do not need a browser tab open, and you do not need to re-invoke after each slice. 1. **An asynchronous run continues itself.** A slice that stops at its row or time limit with work outstanding queues the next slice, under the same run id, and the run stays `running`. It ends when nothing is outstanding, or at the slice cap. At the cap it ends `committed` with a `reason` saying to invoke it again. A cancel, an administrator’s off switch or a per-run ceiling stops it without continuing. 2. **A schedule invokes it with nobody signed in.** Add an entry to `turbobase/schedules.json` and deploy it with `turbobase ext deploy --to `: ```json [ { "name": "migrate-customers-nightly", "scheduleKind": "cron", "scheduleExpr": "0 2 * * *", "scheduleTz": "UTC", "body": { "kind": "process", "process": "acme:migrate-customers-tracked", "input": { "batch": "2026-10" } } } ] ``` * **Only an administrator can deploy one.** The deploy is refused if `process` is missing or names a process that is not deployed. Declaring the process and the schedule that runs it in the SAME deploy is fine — the check reads the processes the deploy will leave behind, not the ones already there. * **A process a schedule runs cannot be removed on its own.** Dropping the process while this entry survives is refused, because the schedule would go on firing against nothing and switch itself off after five failures. Delete both in the same deploy — that is the supported way to retire a process and its schedule — or point the schedule at another process in the same deploy, or keep the process declared. See [Deploy, plan, promote](/extending/deploy-plan-promote/#a-prune-never-leaves-a-schedule-running-a-process-you-removed). * **`name` may not begin with `system.`** — that prefix is the platform’s own recurring jobs, and a bundle schedule using it is refused. * **A schedule written by `ext deploy` runs as the instance’s administrator identity**, and the run’s ledger records the schedule, not a person. * **The schedule’s own run says `success` as soon as the process run is queued.** The process run’s outcome is on the run itself — read it with `turbobase processes runs `. * **A scheduled invoke is skipped, not failed,** while the process or the instance is switched off. * **`input` is checked against the process’s `input` schema on every run,** exactly as the invoke body is. Leave it out and the run gets `{}`. Input that is not a JSON object, or does not match the schema, fails that scheduled run with the field and the reason, and no process run is queued. Repeated failures pause the schedule like any other. A schedule is also how you restart a run that stopped at its slice cap, and it is safe to fire while an earlier run is still going: rows are keyed, so two runs that reach one row write it once. ## What the engine guarantees [Section titled “What the engine guarantees”](#what-the-engine-guarantees) * **Every write goes through the write boundary, as the invoking user.** Hooks, guardrails, row-level security and the write trail apply to a step exactly as they apply to a write the app makes itself. A payload a `before_save` hook rejects fails *that* step with the hook’s own code and field, and no later step is attempted. * **`awaitSource` waits for the source’s verdict, not for the first attempt.** A failed attempt is not terminal — the outbound worker retries — so the wait ends only on `synced` (the source said yes) or on a parked refusal (the source said no). The wait budget defaults to five minutes per step. * **A record the source created but could not be linked back is kept.** When the source accepts an `awaitSource` step’s create and the link from the new record back to its row fails (`write_settle_conflict`), the step ends `failed` with `refusal_code: 'SOURCE_APPLIED_UNLINKED'`, the source’s id on the step’s `externalId`, and the source’s own sentence. The run stops there, but no rollback deletes that row — the record exists upstream, and deleting the row would leave it with nothing pointing at it. Offer `POST /v1/data/:recordType/settle` with the step’s `pgRowId` to link it. * **A wait that runs out is not a failure.** Nothing was refused: the write is on the trail and the source has not answered either way. Behind the one-at-a- time ordering below, exceeding the budget is what an ordinary busy day looks like — so the run stops there with its record intact, ends `committed`, counts the steps it never reached in `outstanding`, and names the waiting step in its `reason`. Branch on that rather than on `failed` if you need to spot a slow source, and **carry it on with a resume** rather than starting over — see [Carrying a stopped run on](#carrying-a-stopped-run-on). * **A run survives a worker restart.** Every step carries an idempotency key and is recorded the moment its write lands, so a re-delivered run resumes at the first unfinished step and never creates a duplicate. For a chain that key is per run. For a migration it is per **source row**, which makes a create step a no-op when the same row is offered again, across runs as well as within one. Update steps and declined steps run again on that later visit; see [the `eachRow` contract](#the-eachrow-contract). * **Rollback is newest-first, through the delete boundary.** With `onFailure: 'rollback'`, every record the run created is deleted in reverse order — `before_delete` hooks see it, and a record that had already reached the source is deleted there too — and the run ends `rolled_back`. That includes a record the source refused after it landed locally. What a rollback never touches is a record the run did not create — a migration step skipped because an earlier run had already moved that source row — and a record the source created whose link back failed (`SOURCE_APPLIED_UNLINKED`, above). **A record whose own upstream create is still in flight IS deleted**: a step that did not await the source, or one whose wait ran out, is recorded as landed, and a rollback removes it here and queues its delete. If the create then reaches the source after the delete was decided, the source can keep a record nothing on the instance points at — so **resume** a run that stopped on a wait rather than rolling it back, and roll one back only when you want the work undone. * **A rollback has its own delete limit, and waits rather than failing.** Every delete that reaches a connected system is capped per source system. A delete your app or a person sends counts against the instance’s delete limit — by default **60 a minute, 1,000 an hour and 5,000 a day**, raised with `guardrails.max_deletes_per_min`, `guardrails.max_deletes_per_hour` and `guardrails.max_deletes_per_day` — and over it the delete is **refused** and the record stays. A run’s rollback is not counted there. Each of its deletes is checked against the run’s own ledger, and one that removes a record **that run created** counts against a separate rollback limit — by default **600 a minute, 10,000 an hour and 50,000 a day**, raised with `guardrails.max_rollback_deletes_per_min`, `guardrails.max_rollback_deletes_per_hour` and `guardrails.max_rollback_deletes_per_day`. Over that limit the delete **waits** for the window to free and is then sent; it is never refused for being over it. A run can never spend more of it than the number of records its ledger shows it created, and a delete of anything else — including a record the run only updated — is an ordinary delete under the first limit. * **`rolled_back` means removed here and on its way to the source.** A run reads `rolled_back` once every record it created has been removed from the instance and its delete accepted for sending. While deletes are still being sent, the run’s `reason` says how many. If the connected system then refuses one, that record comes back, its step returns to what it was, and the run reads `failed` with the refusal named — roll it back again once the cause is fixed. There is no bulk delete endpoint. * **Same-type writes reach the source one at a time, in order.** Two writes of one record type are never committed to the source together, so a source that numbers documents per type cannot hand one number to two of them. This holds for every writer on the instance, not only for processes. ## When the write boundary refuses a step [Section titled “When the write boundary refuses a step”](#when-the-write-boundary-refuses-a-step) A step’s refusal is the boundary’s own, with its `code`. Two are worth knowing before you write a NetSuite migration: * **`ATOMIC_WRITE_REQUIRED`** — a NetSuite transaction create (a credit memo, a vendor credit, a deposit, an invoice, …) arrived with no lines. Header and lines go to NetSuite in one write, so a create step’s `build` must return a non-empty `lines` array: `{ parent: { … }, lines: [{ … }] }`. A document transformed from another one — `parent.created_from_id` set — is the exception; NetSuite copies the lines from its source. * **`write_settle_conflict`** — the record **was** created in the connected system and handed back its id, and linking that id to the row here failed. Do **not** write the row again: a second create makes a second record upstream. The id is on `record_write_state.external_id` for that row, with `reason_code = 'write_settle_conflict'` — read it there rather than parsing it out of the message. You cannot set the row’s `external_id` by writing the row (it is a protected column); link it with the settle verb instead — `POST /v1/data//settle` with `{ "pgRowId": "…" }`, or `turbobase data settle `. It reads the id from the row’s write state (never from you), discards the inbound copy of the same record if one arrived meanwhile, marks the row synced and resolves the failure. It answers `409 NOT_SETTLE_CONFLICT` for a row that is not in this state. ## Scaffold, deploy, and share a rule [Section titled “Scaffold, deploy, and share a rule”](#scaffold-deploy-and-share-a-rule) ```sh turbobase ext new process --record purchaseOrder --then vendorBill --on-failure rollback turbobase ext lint processes/purchase-order-then-vendor-bill.ts turbobase ext deploy processes/purchase-order-then-vendor-bill.ts ``` `ext lint` is the offline check for a process — it reads the file and warns about the id-literal trap below, which is the only rule a process can trip. The four conduit rules it also carries (a weak `idempotencyKey`, a missing `createdFrom`, an extreme `cycleBudget`, a same-source “conduit”) describe a cross-source bridge and are not raised on a process, so `ext lint --ci` is safe to put in your deploy lane: a correct process exits 0. `ext test` is **not**: it invokes a hook’s `run()`, which a process does not export, so every sample comes back failed with `extension default export has no run() function`. A process is exercised by invoking it for a few rows and reading the run ledger. A deploy validates the module the way the loader will and refuses one whose `steps` are not a list, whose step has no `build`, or whose step names a record type the write boundary would not accept — with the field named, and nothing stored. ### Deploying a new version [Section titled “Deploying a new version”](#deploying-a-new-version) `ext deploy` answers `new` for a process the instance did not have, and **`replaced existing` for one it did** (the API’s `outcome` is `written` / `duplicate`). A replace is not a no-op: the new code is stored either way. The instance picks it up within about 30 seconds; a slice that is already running finishes on the version it started with, and the next slice uses the new one. **The stored copy is keyed on the first `id: '…'` literal in the file**, and the running instance serves the module by its own `id`. So make the first literal the process’s own id — not a constant, and with no step, comment or inlined helper carrying an `id:` literal above it. A deploy evaluates the module and refuses a file where the two disagree, with `extension_id_mismatch`, naming the literal it read and the id the module defines; nothing is stored, and a bundle apply (`ext deploy --to `) refuses the whole plan before writing anything. `turbobase ext lint` warns about the same file before you deploy it. The deploy line names the id it stored under and whether it replaced a copy — `deployed → status=active (replaced existing)`. A copy stored under the wrong name by an instance that predates the refusal is still there: both define the same process, only one is served — chosen by the stored names’ order, not by which is newer — so your new code may never run. `turbobase ext plan --to ` lists what is deployed that the project does not declare; a copy there under a step’s id or another stray name is one of these, and `turbobase ext remove ` takes it out. ### A preview runs no process from its branch [Section titled “A preview runs no process from its branch”](#a-preview-runs-no-process-from-its-branch) `turbobase apps deploy --preview` ships an app’s screens and nothing else — a process is installed only by `turbobase ext deploy`, and that is a step of your live deploy, not of a preview. So on a preview build a process the branch **adds** answers `404 { error: 'process_not_found' }`, and a process the branch **changes** runs the version already installed on the instance, not the branch’s. Have the screen say that a process action cannot run from a preview rather than show the 404, and plan for the first real run of a changed process to be the one after it is deployed. Extension files may now import a **relative sibling** inside their own directory — `import { requireMemo } from './shared-rule.js'` — so two hooks (or a hook and a process) share one rule instead of carrying two copies. `ext test`, `ext deploy` and `ext lint` fold the sibling in; an npm package, a Node builtin, or a path that escapes the extension’s directory is still refused. ## Next steps [Section titled “Next steps”](#next-steps) * [Migrating between systems](/extending/migrating-between-systems/) — the recipe for moving data one connected system mirrored into another, and where that shape stops. * [Writing hooks](/extending/writing-hooks/) — validate one record on its write. * [Writing conduits](/extending/writing-conduits/) — bridge a record between sources. * [Sandboxes and testing](/extending/sandboxes-and-testing/) — how extensions execute, and the offline checks that apply. * [Deploy, plan, promote](/extending/deploy-plan-promote/) — ship it. # NetSuite OAuth 2.0 setup > How to issue OAuth 2.0 credentials for a Turbobase instance to call NetSuite — the click-by-click reference behind the console onboarding flow. How to issue OAuth 2.0 credentials for a Turbobase instance to call NetSuite. The values produced here populate your instance’s NetSuite connection in the [console.turbobase.io](https://console.turbobase.io/) onboarding flow. > **Most sign-ups don’t read this end-to-end.** The console walks you through the OAuth 2.0 consent, bundle deploy, and config steps interactively. The click-paths below are the reference for operators who want to drive each NetSuite click by hand — for example, when re-running the flow against a refreshed sandbox. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Admin access to the target NetSuite account (sandbox or prod). * A modern browser. The whole flow is clicks in the NetSuite UI. ## 1. Enable required features [Section titled “1. Enable required features”](#1-enable-required-features) *Setup → Company → Enable Features → SuiteCloud tab.* Check the boxes, then **Save**: * **OAuth 2.0** (under “Manage Authentication”) * **REST Web Services** (under “SuiteTalk (Web Services)”) * **Client SuiteScript** and **Server SuiteScript** (under “SuiteScript”) * **SuiteCloud Development Framework** (under “SuiteCloud Development”) — needed so Turbobase can deploy its bundle into your account. If any are already checked, leave them. If you can’t see this tab, your role is missing the “Enable Features” permission. ## 2. Create an Integration Record [Section titled “2. Create an Integration Record”](#2-create-an-integration-record) *Setup → Integration → Manage Integrations → New.* * **Name:** `Turbobase Sync` (any human label). * **State:** Enabled. * **Authentication tab:** * Check **OAuth 2.0**. * Under “Authorization Code Grant”, check **AUTHORIZATION CODE GRANT** and leave **PUBLIC CLIENT** unchecked. Turbobase uses a confidential client, so copy the client secret NetSuite surfaces alongside the client id. * Check **CLIENT CREDENTIALS (MACHINE TO MACHINE) GRANT**. This is the one box that lets your instance stop depending on the consent’s refresh token: within the hour after you connect, the instance maps its own certificate to this record through NetSuite’s certificate API and mints with it from then on — no reconnect cadence, and no visit to NetSuite’s M2M setup page. Nothing else about the record changes, and the box does not ask you for a certificate; the instance supplies its own. See “Certificate auth” below. * **Refresh Token Validity (in hours):** set this to **720** (NetSuite’s maximum, 30 days). It defaults to `168` — 7 days. Once certificate auth is active this only bounds how long the instance has to complete that switch after a connect; until then it is how often you would have to reconnect. See the note under step 5. * **Scope:** check `rest_webservices` and `restlets`. In the UI these are labelled **REST Web Services** and **RESTLETS**. * **Redirect URI:** `https://console.turbobase.io/ns/auth/callback`. * Uncheck **Token-Based Authentication** and the user-credentials option — pure OAuth 2.0 only. * Click **Save**. NetSuite shows the **Client ID** (sometimes labeled “Consumer Key” in older UI strings) and the **Client Secret** **once** at the top of the next page. Copy them now; the client secret is never shown again. You’ll paste them into the console in step 7. ## 3. The integration role [Section titled “3. The integration role”](#3-the-integration-role) *Already done for you.* The Turbobase bundle adds an integration role to your account when the console deploys it. The role carries the permissions for every record Turbobase syncs. From bundle 2.18.0 the deploy adds **two** roles, and you choose which one your user holds. You do not have to do anything to take the first: | Role | Shown in NetSuite as | What it grants | | ---------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customrole_tb_io_integration` | TB Hybrid Integration | Everything Turbobase can do, including reading your script execution log and managing script deployments. | | `customrole_tb_io_integration_min` | TB Hybrid Integration (min) | The same record access, without the two permissions below. It carries one permission the default does not, so that a connection held under it can renew its own authentication. | `customrole_tb_io_integration` is the **default** — it is the role this guide assigns, and the one every account that installed before 2.18.0 already has. Nothing changes for you if you leave it alone. The narrower role, `customrole_tb_io_integration_min`, drops two permissions: **Manage Roles** and **SuiteScript**. Together those two let the role edit any role in your account and deploy server-side code into it, so if your security review will not accept a vendor credential that can do that, this is the role to assign instead. Everything you actually use Turbobase for still works: every record it syncs, in both directions, and every app built on it. What you **give up** by choosing it: * The **script execution log**. Turbobase can no longer read NetSuite’s own script execution log, so the diagnostics that quote it are unavailable — the log view in your instance, the “Recent UE webhook errors” health check (which reports a warning instead of a result), and the script detail the Customization Analyzer shows. The AI assistant cannot answer questions about why a script failed on your account. * **Script deployment changes.** Turbobase cannot enable real-time sync on a *custom* record type on its own; that needs a bundle redeploy from support instead. Real-time sync on standard records is unaffected. What you **keep**, and it is the reason this choice is safe to take: the narrower role also carries **Manage own OAuth 2.0 Client Credentials Certificates**, which the default role does not need because this guide has you consent as Administrator. NetSuite expires the credential from a sign-in on a fixed cadence — 30 days at most — and the way your instance stops depending on it is to map a certificate of its own, under the role that consented (see “Certificate auth” below). The permission is what makes that possible, so a connection consented under the narrower role renews itself exactly like one consented as Administrator. Without it the connection would stop when that credential expired — a week after consent at NetSuite’s default setting, 30 days at the maximum step 2 asks for — and the only way back would be to reconnect as an Administrator, undoing the switch. To switch an existing connection, assign the other role to your integration user (*Setup → Users/Roles → Manage Users*, then the user’s **Access** tab) and run the OAuth consent flow again from the Turbobase console, choosing that role at NetSuite’s role picker in step 5 instead of Administrator — the token stays bound to the role you consented as, so re-consenting is what moves it. Switching back works the same way, and no synced data is affected either way. For the OAuth consent step below, **consent as Administrator** — unless you have deliberately chosen the narrower role above, in which case consent as that. The bundle’s deploy needs Administrator-level permissions, and at the current version runtime tokens remain bound to whatever role you consented as. The integration role narrows runtime calls in a later step. ## 4. Pick a User [Section titled “4. Pick a User”](#4-pick-a-user) *Setup → Users/Roles → Manage Users.* Pick or create a user with the Administrator role assigned. This is the user you’ll authenticate as during the consent step. For prod, create a dedicated integration user so the runtime OAuth tokens stay bound to a stable account rather than someone’s personal sign-in. ## 5. Run the OAuth 2.0 authorization-code flow [Section titled “5. Run the OAuth 2.0 authorization-code flow”](#5-run-the-oauth-20-authorization-code-flow) The console drives this for you when you connect from the onboarding wizard. To run it manually: 1. Build the authorize URL: ```plaintext https://.app.netsuite.com/app/login/oauth2/authorize.nl ?response_type=code &client_id= &scope=rest_webservices+restlets &redirect_uri= &state= &code_challenge= &code_challenge_method=S256 ``` `` is the account-specific domain (`` — for example `1234567` or `3141592-sb1`). 2. Open the URL in a browser. Sign in as the user from step 4, pick the account from step 4’s user record, and **at the role picker, choose Administrator**. NetSuite redirects to your `redirect_uri` with `code` and `state` query parameters. 3. Exchange the code for tokens: ```bash curl -X POST https://.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code' \ -d 'code=' \ -d 'redirect_uri=' \ -d 'code_verifier=' \ -d 'client_id=' ``` Turbobase’s integration record is a confidential client, so drop `client_id` from the body and add `-u ':'` instead. NetSuite returns: ```json { "access_token": "...", "refresh_token": "...", "expires_in": 3600 } ``` Copy the **refresh token** — it gets pasted into the console in step 7. Access tokens are short-lived (60 min); the runtime mints fresh ones on demand. > **Heads-up — the refresh token expires on a fixed cadence, and the instance is designed to stop needing it.** Using it returns a fresh 60-minute access token but *the same* refresh token, so the deadline never moves. When it passes, every `/token` call answers `invalid_grant` and sync, sign-in and bundle operations stop together. Re-running this connect flow is the only thing that mints a new one — a retry, a redeploy or a restart cannot. Turbobase reports the exact expiry on the instance’s sync-health page and warns 72 hours ahead. > > With **CLIENT CREDENTIALS (MACHINE TO MACHINE) GRANT** ticked in step 2, this deadline matters only once: within the hour after connecting, the instance uses this consent’s token to map its own certificate to your integration record and switches to the certificate grant, which has no refresh token at all (see “Certificate auth” below). If the box is left unticked, the cadence below is what you live with. > > **How long you get is a setting on your integration record, not a NetSuite constant.** Two fields decide it: > > * **Refresh Token Validity (in hours)** — how long the token lives. Defaults to `168` (7 days); the maximum is `720` (30 days). Step 2 asks you to set 720. > * **Maximum Time For Token Rotation (in hours)** — whether NetSuite issues a *replacement* refresh token when you use one, which would move the deadline forward. > > NetSuite renders the rotation field **disabled for a confidential client**, so the chain cannot roll and simply lapses at the validity window. Ticking **Public Client** enables rotation — but measured against a live account, rotation is permitted only until *the original consent* plus that window, after which the chain stops with `invalid_request` even though the token’s own expiry is still weeks away. So a public client lands on the same 30-day ceiling while giving up client authentication. **30 days is the ceiling for this flow either way**, which is why step 2 keeps the confidential client and just maximises the validity. ## 6. Find the Account ID [Section titled “6. Find the Account ID”](#6-find-the-account-id) *Setup → Company → Company Information → Account ID.* For sandboxes the format is like `TSTDRV1234567` or `3141592_SB1`. Lowercase it for the console field: `tstdrv1234567`. The REST hostname derives from the account ID as `${id-with-underscores-replaced-by-hyphens-lowercased}.suitetalk.api.netsuite.com`. For `3141592_SB1` that’s `3141592-sb1.suitetalk.api.netsuite.com`. The console builds this automatically. ## 7. Hand the credentials to your instance [Section titled “7. Hand the credentials to your instance”](#7-hand-the-credentials-to-your-instance) When the OAuth callback lands on the console, it writes the values directly into your instance’s secret store — encrypted at rest, never written to a local file. If you ran the flow manually, paste these into your instance settings on [console.turbobase.io](https://console.turbobase.io/): * Account ID * Client ID * Client Secret * Refresh Token * Access Token (optional but recommended on first run) * Access Token expiry (ms-epoch) If a refresh token ever leaks: revoke it at *Setup → Users/Roles → Active Tokens* in NetSuite (the same screen lists OAuth 2.0 refresh tokens), then re-run step 5 and update the value in the console. The client secret is **required** — Turbobase’s integration record is a confidential client. ## Certificate auth — automatic after the first connect [Section titled “Certificate auth — automatic after the first connect”](#certificate-auth--automatic-after-the-first-connect) Everything above produces an authorization-code credential, and NetSuite caps that grant at 30 days from consent however the record is configured. The grant that has no such cap is **client credentials**: the instance holds a private key, NetSuite holds the matching certificate mapped to your integration record, and every access token is minted from a signed assertion. No refresh token exists to expire. You do not set this up. Once per hour the instance runs a job that: 1. checks whether it already holds a certificate NetSuite accepts, and if so does nothing until 30 days before that certificate expires; 2. otherwise generates a 4096-bit RSA key pair and a two-year self-signed certificate in-process, uploads the certificate through NetSuite’s certificate endpoint using the authorization-code token from your consent, mapped to the **same role and entity** that consented; 3. proves the new certificate by minting with it, and only then stores the material in the instance’s encrypted secret store. Every process picks the certificate up at its next start, and a process whose refresh token dies before then switches over on the spot. Thirty days before the certificate expires the same job uploads a successor using the certificate’s own token, so renewal needs no one either. The previous certificate stays mapped until NetSuite expires it. The only certificate the instance revokes on its own is one it has just uploaded in a run that then failed, so a failed run never leaves an unused certificate on your record. **If NetSuite stops accepting the certificate** — it was revoked, the box was unticked, or the employee it acts as was deactivated — the instance falls back to the consent’s refresh token at once, and the next hourly run maps a new certificate from it. If that token has also run out, the run reports BLOCKED and asks for a reconnect; the run after the reconnect maps the new certificate. **If NetSuite answers the hourly token request with a server error instead of refusing it**, the instance keeps the certificate and tries again next hour, because a brief NetSuite outage is not a reason to replace a working credential. After four hours of that it stops waiting: it treats the certificate as beyond saving and maps a replacement from the consent’s refresh token, exactly as above — so a connection stuck this way repairs itself within about five hours, with nothing for you to do. If there is no usable refresh token left either, the run reports BLOCKED and asks for a reconnect. **What you have to do:** tick **CLIENT CREDENTIALS (MACHINE TO MACHINE) GRANT** on the integration record (step 2) and consent as an **Administrator** (step 3). The upload needs the “Manage own OAuth 2.0 Client Credentials certificates” permission, which Administrator carries — and so, from bundle 2.18.0, does `customrole_tb_io_integration_min`, so a connection consented under the narrower role from § 3 renews itself the same way. **If the box was left unticked**, NetSuite refuses the mapping and the job reports **BLOCKED** in its run output with that exact remedy, then tries again next hour. Tick the box; nothing else needs redoing. The instance keeps working on the authorization-code credential meanwhile, with its 30-day cadence. **Where to see it:** the instance’s sync-health page reports the credential in force — a refresh token with its expiry, or a certificate with its `notAfter` — under the same `NetSuite credential` check, so the countdown gauge and alerts keep working without knowing which grant is live. When the hourly job cannot get a working certificate for your account — NetSuite refused the mapping, or the credential it maps from has itself been refused — a second red check, **NetSuite certificate auth**, appears beside it: it names the integration-record setting to change, carries the hourly job’s own words about which of the two NetSuite said, and disappears by itself on the first run that succeeds — there is nothing to dismiss. That is the row to look for whenever the credential countdown is going down instead of being renewed. In NetSuite, *Setup → Integration → Manage Authentication → OAuth 2.0 Client Credentials (M2M) Setup* lists the mapping. Revoking a certificate there does **not** by itself cut the instance off: while the consent’s refresh token is still valid, the instance falls back to it and maps a new certificate within the hour. To cut the instance off deliberately, untick **CLIENT CREDENTIALS (MACHINE TO MACHINE) GRANT** and revoke the certificate, or disable the integration record. ## 8. Smoke-test [Section titled “8. Smoke-test”](#8-smoke-test) Saving the credentials tests the connection and then starts the first sync in the background — the console doesn’t wait for it, so the wizard moves on as soon as the connection answers. Watch the first pull arrive under **Activity** (**/data/sync/history**) in your app, and read anything that went wrong on **Health** (**/data/sync/health**) or **/data/sync/failures** — see [sync health](/tenant/source-health/). The three errors you’re most likely to meet here: * `401 INVALID_LOGIN_ATTEMPT` on a RESTlet call means the OAuth bearer was minted under a role the script deployment doesn’t audience — almost always because the user picked a role other than the Turbobase integration role at OAuth consent time. Re-run step 5. * `invalid_grant` from `/token` almost always means the refresh token has passed its validity window — 7 days from consent at NetSuite’s default, 30 if you set the maximum. See the heads-up under step 5 for the two fields that set it. Check the sync-health page, which reports the exact expiry instant. Re-run the connect flow from the console to mint a new one; nothing else recovers it. * `403 Permission Violation` means the integration role is missing a record-level permission. Contact — a role refresh from the console fixes it. ## 9. Pin the Turbobase portlet on your NetSuite dashboard [Section titled “9. Pin the Turbobase portlet on your NetSuite dashboard”](#9-pin-the-turbobase-portlet-on-your-netsuite-dashboard) The Turbobase bundle ships a portlet that lists the Turbobase apps each person is allowed to open, and opens any of them already signed in. **NetSuite does not auto-pin portlets** — every user who wants it has to add it to their dashboard once: 1. Open NetSuite home (the dashboard you land on after signing in). 2. Click **Personalize** in the top-right. 3. Click **Add Content** in the sidebar that opens. 4. Find **Turbobase** in the list (search for “turbobase” if needed) and click it. 5. Drag the new portlet to the column you want it in. Click **Done**. If **Turbobase** isn’t in the Add Content list, the bundle install was likely partial — request a redeploy from the console or email . Once the portlet is pinned it shows the apps shared with whoever is looking at the dashboard — the same cards they see on the Apps page in Turbobase, with each app’s own icon and its full description, each opening that app in a new tab, already signed in. Everyone sees their own list and nobody sees an app they were not given. The Turbobase icon above the list opens Turbobase itself in a new tab, already signed in, and the **Build the App** button beside it opens the Apps page, where you can describe a new app at the top. The local sign-in at `/login` is the always-available fallback. Three things worth knowing: * **It needs bundle version 2.17.3 or later.** On an older bundle the portlet is called **Turbobase Access** and may show only an **Open Turbobase** button, show *Your apps could not be loaded* with HTTP status 406, show each app as two initials with no **Build the App** button, or show the cards with the label chips that were on them when your instance last upgraded, so a label added since then shows on the Apps page and not here. Request a redeploy from the console to pick it up. * **A newly shared app can take up to an hour to appear there**, because each person’s list is remembered for an hour so the dashboard is not slowed down. It opens from Turbobase itself straight away. * **If the list cannot be loaded** — your instance is briefly away, or signing in did not answer — the portlet shows an **Open Turbobase** button instead, which takes you to Turbobase already signed in. ## Next steps [Section titled “Next steps”](#next-steps) Whichever NetSuite environment you connect (sandbox or production), the 14-day learning window builds your instance’s rule book from real write rejections. * **Have a sandbox?** Start in the sandbox-first path — refresh the sandbox from production, learn safely for 14 days, then carry the rule book into a fresh production-pointing instance. * **No sandbox or smaller account?** Use the production-direct path. The same reactive loop runs against real traffic; watch the failures page in your app more attentively during the first week. Questions? Email . # Releases and adopt notes > What each Turbobase release changes for existing app projects — one actionable line per change, newest release first. Every Turbobase release that changes something an existing app project has to act on lists it below, newest first. Work the entries newer than the version your project last adopted: `turbobase project adopt` writes exactly those into your project’s `ADOPT.md`, and your own instance serves the same list at `GET /v1/catalog/adopt-notes`. A release with nothing for app developers is simply absent — silence is the signal that there is nothing to adopt. ## v1.50.0 [Section titled “v1.50.0”](#v1500) * **Handle a partial answer from `POST /v1/batch`: the whole call now has its own deadline.** Until now a batch either came back complete or the front door gave up on it and your request failed with nothing in the body. A large fan-out of slow reads now answers in time with whatever finished, so check each slot before you render it — a batch that met the deadline comes back partial rather than failing. * **Tell a sub-query that never ran from one that was tried: read `results[i].notRun`.** A slot the deadline refused answers the same `504` an aborted read answers, plus `notRun: true` — present only on a sub-query that was never sent, absent on every other slot, the way `truncated` already behaves. Its `body.error` says so in words if you log it. Nothing changes for a call that finishes inside the deadline: no slot gains a field. * **Ask again for the slots that did not run — not the whole batch.** Re-sending all of it re-runs the sub-queries that already came back and re-enters the same queue that ran out of time. Collect the indexes carrying `notRun`, send those queries on their own, and merge them into what you have. Splitting a wide first paint into two narrower batches is the better fix if you meet the deadline often. * **Give your app a page to open from a NetSuite create form, if you want one.** The “TB Open in Turbobase” button can now also appear while a user is creating a new record: the NetSuite admin sets “Turbobase path on new records” on the script deployment (e.g. `/a/orders/new`), and the button opens that path exactly as set, signed in as usual, with no `source`, `recordType` or `recordId` appended — the record has not been saved yet. Nothing changes for a deployment that leaves the parameter empty, and the VIEW button still appends all three. ## v1.49.0 [Section titled “v1.49.0”](#v1490) * **Offer `resumeProcessRun(runId)` instead of your own “finish what the run left” screens.** A process step that declares `awaitSource` waits a bounded time for the connected system’s verdict; past that budget the run ends `committed` with the steps it never reached counted in `outstanding`. Until now nothing could carry it on, and invoking the process again started a NEW run whose step keys were its own — so the records the first run made were created a second time. `resumeProcessRun` posts to `POST /v1/processes/runs/{runId}/resume`, which puts the SAME run back on the queue at the step it stopped on: the steps its ledger already recorded are passed over — a step whose `when` declined as well as one that wrote, because the run reached it and decided — the one whose verdict never arrived is waited for again, and the rest of the chain runs. Only the steps the run never reached are performed, so nothing is written twice and nothing the run chose not to do happens behind you. Answers `202 { runId, state: 'running', queued: true }` — watch the run until it reads `committed` with `outstanding: 0`, exactly as you do after an invoke. * **Branch on `409 process_run_not_resumable` rather than offering the button on every stopped run.** Only a run that ended `committed` with work outstanding can be resumed. A run that is `queued` or `running` has not stopped, a `failed` or `rolled_back` one needs its refused step re-keyed rather than re-offered, a `cancelled` one was stopped by a person, and a `committed` run with nothing outstanding has finished — each answers `409` naming the state on the body, with nothing queued. A process declared `eachRow` answers `409 process_is_a_migration`: its writes are keyed per source row, so invoke it again to carry one on. The resume is open to whoever invoked the run and to an administrator, and anyone else gets the same `404 process_run_not_found` the run read gives them. Two resumes in quick succession start one continuation — the second answers `409`. * **Run `turbobase processes resume ` when nobody has built a screen for it yet.** The same door from a terminal, on an `extensions:deploy` token owned by an administrator, beside `processes cancel` and `processes rollback`. * **Stop telling readers to roll a stopped run back and start over.** The guidance in *Author processes* said to roll back a run that stopped on a wait once that step’s record had reached the source; resuming it is now the answer, and a rollback is for undoing work you do not want. A record the connected system applied but could not link back is still kept by every rollback (`SOURCE_APPLIED_UNLINKED`), and a resume onto one of those now records it the same way — so a resumed run no longer deletes a record that exists upstream. * **Undo the shallow-schema workaround in a process `input`, if you added one.** A process (or hook, or conduit) deployed from an app is read into the platform by a walk that used to stop at six levels and drop everything below in silence. A JSON Schema spends five of those on its own nesting — `input` → `properties` → a field → `items` → `properties` — so every per-field schema inside an array’s items was lost while the `additionalProperties: false` beside them survived, and the process then refused every non-empty array before it ran (`targets.0 must NOT have additional properties`). The walk now goes 64 levels, so an input that hoisted its item schema into `definitions` and pointed at it with `$ref` purely to stay shallow can be written inline again. Nothing is required of you: a hoisted schema keeps working. * **Expect a deploy to be refused, by name, where it used to be accepted and then misbehave.** Past 64 levels of nesting, or more than 256 keys in one object or entries in one array, the deploy now fails with an error naming the path that hit the limit instead of registering a schema with the deep part cut off. A definition that was over either limit was already validating the wrong shape — accepting bodies it should refuse where a `type` union, a nested `items` or an `anyOf` member went missing, and refusing correct ones where a `properties` did. Flatten the shape, or declare the repeated part once in `definitions` and reference it with `$ref`. ## v1.48.0 [Section titled “v1.48.0”](#v1480) * **Read `line_number` on `order_fulfillment_line` and `item_receipt_line` as the line’s own NetSuite id, not as a position.** It always meant that on rows a REST read wrote. Rows written by the scheduled poll held a 1-based position and rows written in realtime a 0-based one, so the value changed whenever the record was re-read. Each row takes the id the next time its record syncs. Keep ordering lines by `line_number` if you do already: the order is stable, but it is not guaranteed to be the order NetSuite displays them in. Join to `system_note.line_index` on it as documented. * **Read `line_index`, not `line_number`, on `order_fulfillment_line` and `journal_entry_line` — only `item_receipt_line.line_number` is kept for good.** Two v1.46.0 texts disagreed: the adopt note said those two columns are dropped a release later, while the header of the `line_order` migration called all three `line_number` columns frozen. The adopt note is right; the migration header overstated it, and migrations are not edited once shipped, so this is the correction. Until the two are dropped, `project types` still names `line_number` as the paging key for them in `SEEK_KEYS`, because `line_index` arrived nullable — paging through `SEEK_KEYS` keeps working while the column exists. Order and display lines by `line_index`. * **Return a Promise from an update step’s `pgRowId`, `externalId` or `expectedSyncVersion` when the value needs a read.** A deployed process has always awaited them, but the `@turbobase/extensions` type said they were synchronous, so the natural code — read the row’s current `sync_version` through `ctx.query`, then hand it over — did not type-check, and authors passed values across from `when` by hand. The type now allows a Promise, and the engine awaits it on every path. The order is unchanged: `when`, then the address functions, then `build`. * **Read `SOURCE_APPLIED_UNLINKED` on a process step, and link the record instead of telling the user to clean it up by hand.** When an `awaitSource` step’s create was APPLIED by the connected system but linking the new record back to its row failed (`write_settle_conflict`), the step used to be recorded `SOURCE_REFUSED` — and a rollback then deleted the row, which had no `external_id`, so the record stayed in the connected system with nothing on your instance pointing at it. The step is now `failed` with `refusal_code: 'SOURCE_APPLIED_UNLINKED'`, the source’s id on the step’s `external_id` and the same message as before, and no rollback — automatic or `POST /v1/processes/runs/:runId/rollback` — deletes its row. The run still stops there. Offer `POST /v1/data/:recordType/settle` with the step’s `pg_row_id` to link it. Code that matched the message rather than the code keeps working; code that branched on `SOURCE_REFUSED` for this case should branch on the new code. * **Add `turbobase project skills` to `.claude/hooks/session-start-refresh-types.sh` once, so the platform’s skills stay current in this project.** The skills the scaffold writes that are platform knowledge — `write-a-process` and `business-rule-to-hook` — used to be written at `init` and never again, so nothing the platform learned afterwards reached your sessions. They now carry a `platform-maintained` line, and `turbobase project skills` rewrites them from the installed CLI. Paste this at the end of the hook, after the `project adopt` line: ```sh if turbobase project --help 2>&1 | grep -qE '^ +skills( |$)'; then turbobase project skills >/dev/null \ || echo "turbobase: \`turbobase project skills\` failed — the platform skills were NOT refreshed." >&2 fi ``` The first run replaces an older copy you never edited and saves it as `SKILL.md.bak`; a copy you DID edit is left alone and named, so move your notes to `INSTANCE-LEARNINGS.md` and delete it to take the platform’s. Your own skills are never read. New projects get the hook line from `init`. * **Stop probing the session before calling an `/api/account/*` route, and send a `turbobase:session_dead` user to `/login` as the docs already say.** A role edit or a role-changing deploy ends every signed-in session at the data plane with `turbobase:session_dead`, and the instance’s own pages used to answer that by deleting the session cookie — so the next console call, or `/login` itself, asked for a password. They now ask the instance to re-mint the session first: a person whose access changed keeps working with their new access, and only a session that was signed out, superseded or suspended is cleared. The documented behaviour of `/login` is now what happens. * **Refresh `.claude/skills/write-a-process/SKILL.md` from a new scaffold.** It gains six traps a production app met moving its writes onto processes: a chain that stops cannot be resumed and invoking again creates again; the invoke takes no idempotency key; `SOURCE_APPLIED_UNLINKED` and how to link its record; async update addresses; delete-only `onRefused` and bare scope refusals; and that a preview cannot run a new or changed process. Run `turbobase project init` in an empty directory and copy that one file over yours — never `--force` over your project, which overwrites everything. ## v1.47.0 [Section titled “v1.47.0”](#v1470) * **Keep the `line_index` fallback when you sort a NetSuite document’s lines by `line_order` — the column is not guaranteed to be filled by the next poll.** The v1.46.0 note said a document’s lines are rewritten with `line_order` the next time it is read, within four hours. That holds only for a document that changed: a re-read that finds nothing new writes nothing, so an unedited document kept `line_order` null. This release fills it once, on upgrade, for every stored NetSuite line whose position can be read exactly from the document it was synced with. A line it cannot place stays null until the document next changes in NetSuite, so keep ordering by `line_order` with nulls last, then `line_index`. PostgREST: `purchase_order_line.order=line_order.asc.nullslast,line_index.asc`. ## v1.46.0 [Section titled “v1.46.0”](#v1460) * **Declare `on: 'after_save'` on a conduit to react when a record is saved on your instance, whoever saved it.** Until now a conduit only woke up when a record arrived from, or landed in, another connected system — so a save made here, by your app through `POST /v1/data/:recordType`, by a process, by the in-product agent, by Studio or by another conduit, triggered nothing at all. It fires once per COMMITTED save, after the save commits, through the same dispatcher the two existing triggers use: the run shows up on `turbobase logs --conduit`, idempotency and the cycle budget apply unchanged, and a save that was refused or rolled back fires nothing. A record ARRIVING from a connected source is still `after_canonicalize_inbound`, so a synced record never fires twice. * **Leave `idempotencyKey` off an `after_save` conduit.** With no key declared, each banked save gets its own, which is what makes two saves of one record two runs. Declare one and it is used exactly as written — and a record saved here has no external id, so `ctx.externalId` is its own surrogate key and is the same string for the record’s create and every later edit. The conventional `':${ctx.externalId}'` therefore dedups the second save into the first and the conduit fires once in that record’s lifetime. `turbobase ext lint` asks for `ctx.externalId` in a declared key, which is right for the two inbound events and wrong for this one. If you need your own key here, put a field from `ctx.change` in it. * **Read `ctx.change` in an `after_save` conduit’s `from.when` instead of firing on every edit.** It is `{ kind: 'insert' | 'update', fields: [...] }`, and `fields` names the columns the writer actually supplied — so `ctx.change.fields.includes('status')` is a gate rather than something you work out in the body. Both the gate and the transform see it. It is ABSENT on the two existing triggers, so a conduit you already have reads exactly what it read before. * **Read `ctx.savedBy` to refuse your own writes.** It is `{ kind: 'app' | 'process' | 'agent' | 'studio' | 'conduit' | 'user', id? }`, with the conduit’s id when a conduit made the save. **A conduit’s own write is one of these saves** — the row it writes into the target fires `after_save` under the pair its `to` names, so a conduit that listens where it writes feeds itself. Gate on `ctx.savedBy.id !== ''`: that stops the loop before it runs, where the cycle budget stops it after. Absent on the two existing triggers. * **Point a conduit at `from: { source: 'turbobase', recordType: 'proposal' }` to react to a change request.** `turbobase` is a reserved source for the platform’s own records — it is not a connector and never will be, so do not use it as a `source_system` anywhere else. A change request fires on filing, on classification and on every status change, each run carrying `{ id, title, body, app_slug, filed_by, status }` and nothing else. The projection is fixed: a column added to the table later does not join it. * **Point a conduit’s `to` at `turbobase:proposal` to FILE a change request from a connector record** — a message in a Slack channel becoming a request, for instance. The target may create a DRAFT and nothing more: a patch that names `id`, `status` or any other lifecycle field is refused, and the ledger row says which key refused it. Where the request came from is recorded on the created request’s `solution_target`, and the filing itself reaches an `after_save` conduit as `savedBy: { kind: 'conduit', id }` — so a conduit that both files requests and reacts to them can tell its own from a person’s. * **Expect a conduit whose `to` names a system this instance does not have to be refused at deploy time.** `turbobase ext deploy` previously accepted a target under any unknown source — including a mistyped connector id and `turbobase:` — and the conduit then failed on its first run with `unresolved target`. It now 400s with `conduit_target_unknown`, naming the pair. A conduit already stored with such a target is refused at the apply layer with the same sentence instead of running. If you have one deployed against a typo, this is where you will find out. * **Declare `after_save` HOOKS on records your app writes and they now run.** `POST /v1/data/:recordType` ran `before_save` and then nothing once the save committed, so an `after_save` hook on a record type an app writes never saw the app’s own saves — only ones arriving from a source. It now runs post-commit, observe-only, in the shape `after_delete` already uses at the same boundary: it reports `direction: 'standalone' | 'outbound'` and `origin: 'user'`, it cannot refuse or revert the write, and a throw out of it does not fail the write. A hook you declared and assumed never fired for app writes does now. * **Declare `on: 'after_delete'` on a conduit to react when a record is deleted on your instance.** Until now a conduit could react to a record arriving, to a record landing in another system and to a record being saved — and to nothing at all when one went away, so “unpublish the counterpart”, “close the ticket” and “retract the announcement” were unbuildable. It fires once, after the delete commits, and `ctx.payload` is the record’s LAST STATE, which is the one thing a deletion reaction cannot read back for itself. A delete your guardrails or a `before_delete` hook refused fires nothing, and a repeat delete of a record that is already gone — still a `200`, because a delete here is idempotent — fires nothing either. `ctx.change` is absent on this trigger, as it is on the two inbound ones. * **Read `kinds` and `origin` on a `turbobase:proposal` conduit.** The change- request projection was `id, title, body, app_slug, filed_by, status`; it is now those six plus `kinds` — the solutioning kinds the request has been classified as, `[]` until somebody classifies it — and `origin`, which says how the request arrived. `origin.channel` is one of `widget`, `conduit` or the request’s own creator (`authored`, `request`, …); a widget request also carries `origin.route`, the screen it was filed from, and a conduit-filed one carries `origin.conduit_id`, `origin.from_source`, `origin.from_record_type` and `origin.from_external_id`. Keys that do not apply are absent rather than null, so test for the key. * **Gate on `ctx.change.fields.includes('kinds')` to react when a request is CLASSIFIED.** Classifying a request now fires `after_save` on `turbobase:proposal` with `kinds` named as what changed — before this, the only run a request ever produced was its filing, where `kinds` is empty by construction, so a conduit keyed on classification could not be written. A classification reports `kinds` and nothing else: it does not report `status`, so a conduit watching for a decision on a request no longer fires when somebody merely works out what the request is. * **Set `app_slug` and `filed_by` in a `create-draft` patch** to say which app a request a conduit files is about and who reported it. Both are fields the projection already published and neither could be set, so a conduit-filed request arrived with two of its fields permanently null. An `app_slug` your instance does not have is REFUSED, naming the slug, and nothing is created. `filed_by` is recorded as REPORTED by the conduit and never as a signed-in user, so a request’s `created_by` still only ever names somebody who authenticated. * **Address a Slack `channel_message` to a person by email** to send a direct message. `raw.channel` took a channel id, `#name`, a bare name or Slack’s own `<#C…|name>` markup; an email address now resolves against your workspace’s mirrored members and the message is delivered into that person’s direct-message conversation. An address no member carries is refused with the address named, and a Slack app installed before this shipped is refused with `im:write` named — re-install the Slack app from Settings → Slack to grant it. Everything about a channel post is unchanged. * **Name a process in a conduit’s `to` to start it:** `to: { source: 'turbobase', recordType: 'process', process: '' }`. The transform’s patch becomes the process input, so the transform is where you shape the firing record into whatever the process declares it takes, and the run is recorded on the conduit ledger like any other target. A process your instance has not got is refused at `turbobase ext deploy`, naming it. * **React to a release and to a published knowledge page.** Two new reserved records publish into the same `after_save` seam: `turbobase:app_release` (`id`, `app_slug`, `app_name`, `version`, `deployed_by`, `deployed_at`), which fires on a PRODUCTION deploy and not on a preview; and `turbobase:knowledge_page` (`id`, `slug`, `title`, `visibility`, `published_by`, `published_at`), which fires when a page is published and not when one is written, edited or taken back to draft. Both may only be reacted to — a conduit naming either in its `to` is refused at deploy. * **`turbobase ext lint` has new advice about an `after_save` or `after_delete` idempotency key, and it reverses what it used to say on those triggers.** A declared key that carries nothing about the save now warns `lifetime-idempotency-key`: on a save trigger `ctx.externalId` is the same string for the whole of a record’s life, so a key built on it alone dedupes every later save into the first and the conduit fires once per record and never again. Omit the key, or include something from `ctx.change`. The advice for `after_canonicalize_inbound` and `after_sync_success_outbound` is unchanged — there `ctx.externalId` is exactly the right key. * **A banked save that cannot be dispatched is now parked after five attempts and reported as a sync failure**, instead of being re-claimed every five minutes for ever. The failure names the record and the conduits that were waiting for it, and the row is kept rather than dropped, so an operator who fixes the cause can replay it. Nothing changes for a save that merely fails once and then works: it is still dispatched, exactly once. * **Turn on “Classify a change request when it arrives” (`solution.classify_on_arrival`) to have every new request classified as it is filed**, from any channel, instead of waiting for an admin to mark it ready for solutioning. Off by default, because it spends one planner model call per filed request. It records the kinds only: the request’s solutioning state does not move and no draft solution is seeded. * **Classifying a request no longer forgets what the request knew.** The solutioning planner used to replace a request’s whole `solution_target` with its own hints, so classifying a request filed from the in-app widget could drop the app it was about, the screen it was filed from and the filer’s address — which is the field `filed_by` is read from, so a classified request could read as anonymous. The planner’s hints are now merged onto what the request already carried, and `setProposalTarget` merges rather than replaces. A classification that names no target of its own leaves the request’s target exactly as it was. * **Share a file into Slack with a new `file` record on `source_system: 'slack'`.** It takes two requests: POST the bytes to `/v1/data/file/uploads` with `content-type: application/octet-stream` and keep the `upload.upload_id` it answers, then create the record with that handle on `raw.upload_id`, the destination on `raw.channel` (a channel name, a channel id, or a person’s email address) and the file’s name on `path`. `raw.thread_ts` puts it in a thread, and `raw.initial_comment`, `raw.title` and `raw.alt_txt` are optional. The row settles `write_status: 'synced'` with Slack’s own file id as its `external_id`, so read the status rather than treating the create’s 200 as a file in the channel. `list_record_types` publishes the required paths as `required_inputs` — read them rather than hard-coding the list. * **Do not edit or delete a Slack `file` row.** Both are refused — the create with 422 at the boundary, a privileged enqueue or conduit with `code: 'FILE_SHARE_IS_FINAL'` — because Slack publishes no verb that replaces a shared file, and sending it again would put a second copy in the channel. Share a new file instead. `list_record_types` publishes `ops: ['create']` for it. * **Pin the source when you ask the catalog about `file`.** Four connectors now publish that record name and the bare-name fallback in `GET /v1/catalog/records/file` and `GET /v1/catalog/columns?types=file` resolves to Slack rather than Google Workspace, which changes the table and the read capability it describes. Pass `?source=google_workspace` (or `github`, `azure_blob`, `slack`) and nothing collapses. The four `source:recordType` couples are unchanged. * **Read the number out of an over-size upload refusal.** `POST /v1/data/:recordType/uploads` one byte over the 8 MiB ceiling used to answer Fastify’s own `Request body is too large`, which named no limit; it now answers 413 with `rejection.code: 'UPLOAD_TOO_LARGE'`, `field: 'body'` and the byte limit in `rejection.message`, the same shape it already sent for a larger overage. Nothing to change if you were reading the status; parse the message rather than hard-coding 8 MiB if you surface the limit. * **Expect `files:write` on the Slack app.** A workspace connected today already grants it. One connected before file sharing existed does not, and a share then ends `write_status: 'blocked'` with `reason_code: 'source_permission_missing'` and a message naming the permission — re-install the Slack app from the instance’s Settings → Slack. No change to any app, but surface that message rather than retrying: no number of attempts grants a permission. * **Read `label` on a FeedHive instance to get the workspace’s labels.** A new read-only record type, `feedhive:label`, lands on the shared `label` relation with each label’s name: `/rest/v1/label?source_system=eq.feedhive`, or `list_records` on `label`. It needs `read:label`, which is the capability `github:label` and `asana:asanaTag` already use, and it appears in `/v1/catalog/records` and in `turbobase project types`. It refreshes on every sync, so a label added or renamed in FeedHive arrives on the next one. * **Set `raw.labels` on a FeedHive `social_post` to file a post under a label.** Accepted on the create and on the update, as an array of label **ids** — read them off the `label` relation above; the name is not accepted. A mirrored post now also carries its own label ids in `raw.labels`, so an app that reads a post and writes it back keeps the labels it had. Omit the key to leave a post’s labels alone: `labels` REPLACES them, so an edit sending `[]` would strip what somebody set in the FeedHive calendar — which is also why clearing a post’s labels is not something this field can express yet. * **Expect `reason_code: 'LABEL_UNKNOWN'` on a FeedHive post filed under a label the workspace has not got.** The post is SAVED and then refused when the write is sent, so read it off `record_write_state` rather than from the response to your write — the label is named in the message. Nothing reaches FeedHive, and one unrecognised label refuses the whole post rather than publishing it under the rest. A workspace whose labels have not been mirrored yet refuses too, and says that is why — wait for the next sync rather than treating the label as missing. Only a label you are ADDING is checked, so an edit that leaves a post’s labels as FeedHive reported them is never refused for them; a post naming no labels is unaffected and is published exactly as before. **“Already there” means what FeedHive told us about that post, not what the row says** — writing an unknown label onto a mirrored post’s `raw.labels` and then editing the post does not establish the label, and is refused like any other. * **Read a line’s cost-tracking label from `class_name` / `department_name` / `location_name`, not out of the line’s `raw`.** Every line-bearing Xero record — invoice, bill, credit note, supplier credit note, purchase order, spend money and manual journal — now projects each line’s `Tracking[]` entry into the line table’s existing dimension columns, so an invoice line tagged with a “Region” option reads `class_name = 'West'` and `class_id = 'xero:{TrackingOptionID}'`. **When the source sends an entry with no option id the `_id` column stays NULL and the `_name` is still filled**, so match on the name when the id is absent rather than treating the line as untagged. The whole `Tracking[]` array is still kept in the line’s `raw`, so nothing you read today stops working. * **Select a source’s cost-tracking axes from `/rest/v1/segment` and their values from `/rest/v1/segment_value`.** These are new and they are the canonical store for every source’s dimension values: one `segment` row per AXIS (a Xero tracking category, a Business Central dimension, a NetSuite custom segment, and NetSuite’s own class / department / location), and one `segment_value` row per value on it. A value carries `segment_pg_row_id`, `canonical_segment`, `name`, `parent_id` / `parent_name`, `is_inactive` and `raw`. Count one axis’s values with `segment_value?select=*&segment_pg_row_id=eq.{id}` and `Prefer: count=exact`. An archived value is present with `is_inactive = true` rather than missing, so filter on that column if you only want the ones a user can still assign. * **`/rest/v1/classification`, `/rest/v1/department` and `/rest/v1/location` keep working unchanged, and are the ones to stop writing to.** They now hold the subset of `segment_value` whose axis fills that typed slot, kept in step by the database, with the same `pg_row_id` on both sides — so every list read, filter and `pg_row_id` reference you have today is unaffected. They become read-only views in the release after this one, so **move any WRITE you make to one of them onto `segment_value`** (set `segment_pg_row_id`; the slot is derived). Reads need no change then either. * **Replace an embed of a dimension — `order?select=*,location(*)` — with `order?select=*,segment_value(*)`.** PostgREST resolves an embed through a foreign key, and every `_pg_row_id` link now references `segment_value`. No app in either repository embeds one today (all reads measured were plain list reads), so this is here for completeness rather than as a break anybody is expected to hit. * **Stop binding a source axis to a canonical one in your own code.** Which typed slot a source axis fills is now a row — `segment_mapping`, one per `(connection_id, source_system, segment)`, carrying `canonical_segment` and the source field for the outbound direction. Read it instead of hard-coding a pairing: a migration app that assumed “QuickBooks class → NetSuite class” should take the pair from this table. The mapping is created the first time an axis is seen and is never recomputed, so it is stable across a rename of the axis upstream. **Read it, do not rewrite it** — changing `canonical_segment` on an existing row is not supported in this release: the values move slot but the `classification` / `department` / `location` mirror does not follow them, and lines already projected under the old slot keep their typed columns until they are next synced. * **Stop treating “this source keeps no class or department” as a fact about the source, and ask `/rest/v1/segment?source_system=eq.{source}` per connection instead.** Xero is the case that changes: it mirrored no dimension record of any kind before this release, so an app that offered a Xero customer no region or cost centre — or asked them to type the names in by hand — was right and is now wrong. Every source that mirrors an axis answers through the same two tables, so this is one read per connection rather than a per-source list to keep up to date, and `segment_mapping` says which canonical slot each axis fills. An empty answer still means the connection has no axes, so the hand-typed path is a fallback rather than something to delete. * **Read every axis a line carries, including the ones with no typed column, from `/rest/v1/line_segment_value`.** A canonical line has three typed dimension slots and a source may define more axes than that — Business Central allows eight, a NetSuite account any number of custom segments — so each line’s full set of assignments is listed here, one row per axis, keyed by `line_table` and `line_pg_row_id`. It is read-only in this release: the values beyond the typed columns still reach the source through the line’s `raw`. **A row is never more readable than the line it names**, under the caller’s own rights and the line table’s own rule — so a user who cannot read an invoice reads none of its lines’ labels, and a reader restricted to one class reads neither the journal line tagged outside their scope nor its labels. It can be LESS readable, on the one line table whose own rule names no dimension column: `turbobase.check_line` cascades from its header’s subsidiary, so a class-restricted reader keeps a spend-money line and loses its labels. So a short label list is a scope answer rather than a sync gap, and the thing to reconcile it against is the line’s own typed dimension columns, not the line count. * **Expect a scope-restricted reader to see FEWER journal lines than before.** `turbobase.journal_entry_line`’s read rule tests `class_id` and `department_id`, so now that those columns carry a value, a user whose class or department access is restricted stops seeing journal lines tagged outside their scope. That is correct scoping rather than a regression, and a reader with no restriction configured sees exactly what they saw before — but if your app shows journal lines to restricted users and assumed they saw all of them, re-check those screens. Spend-money lines are unaffected: `turbobase.check_line`’s rule cascades from its header’s subsidiary and names no dimension column. * **A Xero line’s tracking is read-only outbound, and that is now recorded rather than implied.** Editing a Xero line’s `class_id` does not reach Xero: the writer rebuilds `Tracking` from the line’s inbound `raw`. The mapping row says so — `direction = 'inbound'` and a NULL `source_field` — so check it before offering an edit. NetSuite’s class / department / location round-trip as they always did. * **Stop branching on `record_write_state.message` for a held write — three of those sentences changed.** A write the connected system refused on its own access control (`reason_code: "permission_denied"`), a write the write-back breaker is withholding (`reason_code: "connection_refused"`), and a write whose target record is gone upstream (`reason_code: "NOT_FOUND"`) each used to carry the generic *“Syncing is held — your team has been notified. No action is needed from you”*. All three now carry a sentence about the actual condition: what refused, whether editing the record releases it, and who has to act. `status` is still `blocked`, `reason_code` is unchanged on all three, and `fields` is still empty — so an app branching on the code or the status needs no change. An app that matched the prose, or showed it as proof that nothing was needed, must stop: the permission and gone-upstream sentences now say somebody at the other end has to act. * **Read `summary` off `GET /v1/events` instead of looking the event code up yourself.** Each row in the response now carries a resolved human sentence for that occurrence. It is derived from the row, never stored, so correcting a wording reaches rows already written. For `sync.failure_recorded` the sentence depends on the failure’s classification: a held refusal no longer claims the record “is re-attempted on the next run”, while a retryable one still does. Every other code resolves to the same sentence it always had. The field is optional on the wire — an instance older than this release sends none — and `turbobase logs --json` now prints it. The rendered one-line form is unchanged. * **Stop treating `500 write_failed` on a retried `POST /v1/data/:recordType` as “it may or may not have landed”.** A retry carrying an `idempotencyKey` the caller itself committed **on or after this release** is now answered `200 { ok: true, replayed: true }` with the first attempt’s `pg_row_id` and `external_id`, for every caller — including the three that used to get the failure back every time, forever, for that key: a role holding `write: