---
title: "The words we use"
description: "The fixed vocabulary of MainSDK docs, specs and code, with the words to avoid, so a developer or an agent can search one word for one thing."
section: "concepts"
canonical: "https://mainsdk.dev/docs/concepts/vocabulary"
updated: "2026-10-28"
---

# The words we use

> The fixed vocabulary of MainSDK docs, specs and code, with the words to avoid, so a developer or an agent can search one word for one thing.

Canonical: https://mainsdk.dev/docs/concepts/vocabulary · Updated: 2026-10-28

MainSDK uses one word for one thing. This page is the list. If you write docs, specs or code for MainSDK, use the left column. If you are an agent, search for these words and none of the others.

## The ten words you need first

| Say | It means | Example |
| --- | --- | --- |
| interface | One standard contract for a capability. | `auth`, `db`, `ai`, `files` |
| driver | The code behind an interface for one provider. | `resend` for `email`, `s3` for `files` |
| provider | The third-party service a driver talks to. | Stripe, Amazon S3, Anthropic |
| `main.yaml` | The file that declares what your app is, needs and may do. | `driver: s3` under `files` |
| check | The `mainsdk check` command, and one run of it. | `mainsdk check --json` |
| finding | One problem a check reports, with a code and a fix. | `MAIN-SECRET-0002` |
| action | Logic written once with `action()`. | `orders.refund` |
| tool | An action exposed over MCP, or a function a model may call. | an MCP tool |
| coding agent | An AI that writes your code. | Claude Code, Cursor, Codex |
| app agent | An agent that runs inside your app and acts for a user. | a support bot |

## The rest

| Say | It means | Not |
| --- | --- | --- |
| adapter | The import that wires MainSDK into a framework: Next.js, Hono, Express. | a driver |
| runtime adapter | The per-runtime code inside MainSDK, picked by export conditions, where `node:*` may appear (spec portable-core). | adapter (alone, for this), shim |
| language SDK | One native MainSDK library for one language: `mainsdk` on npm (the reference), the `mainsdk` crate, the Python `mainsdk` package, `mainsdk.dev/go`. Each implements the same interfaces, `main.yaml`, codes and checks in its own idiom (ADR-0075). | binding, port, wrapper, client library |
| library | What MainSDK is in every language: imported like any package, with nothing to run beside it. | core (for another language's SDK), sidecar, runtime |
| contract layer | The data every language SDK shares: the TypeSpec contracts and their wire formats, the `main.yaml` schema, the code registry and the parity vectors. Never code (ADR-0075). | shared core, common runtime |
| parity vectors | Golden test cases as JSON, exported from the TypeScript reference (spec testing-kit), that a language SDK may adopt to show it gives the same results and codes. Optional data, never a gate on API shape. | conformance suite (for this), golden files |
| conformance suite | The tests a driver passes for each interface version it claims (spec testing-kit). | parity vectors (for this), test suite |
| integration | The docs page for one provider and the drivers it serves. | a driver |
| connector | An outbound link to a customer's compliance or GRC system (phase 3). | a driver |
| preset | A named starting `main.yaml`, chosen at `init`. A template is a whole starter app. | profile, template (for a preset) |
| skill | The `SKILL.md` a coding agent loads. | |
| limit | A ceiling on spend or calls for a user, a feature or the app, set under `limits`, or for a tenant, set by its plan under `plans.<name>.limits`. As a list option, `limit` is the page size. | cap |
| budget | The spend and call allowance of one app agent, set under `agents.<name>.budget`. | |
| guarantee | A promise an interface keeps whatever the driver. | feature |
| category | One of the twelve groups every interface and spec belongs to, such as Identity and access or Reliability and operations; the catalog's `category` and a spec's `category:` (ADR-0065, [Categories](https://mainsdk.dev/docs/concepts/categories)). | section (a `main.yaml` key or a docs part), area (the org topic word or a code's `AREA`), domain |
| alert | A problem that should reach a person, raised by an SDK source or `alerts.raise`, deduped by its key and sent through `alerts` routes (spec alerts). Not a log record, which every alert also writes. | page, incident, notification (for this) |
| recipient (alerts) | A named group of notify drivers under `alerts.recipients`, such as `oncall` with PagerDuty and Slack. Not a receiver, which is a host allowed to receive labelled values. | receiver, destination, contact point |
| escalation | Sending an alert that nobody acknowledged to the next recipients after a set time, under a route's `escalate`. | |
| baseline | The named minimum every app meets: Main 27. | standard |
| region | Where data is stored: `us`, `eu` or `in`. | zone |
| permissions | The `main.yaml` section that declares what a server-side app uses on its own machine: folders, system facts and programs. | capabilities, entitlements |
| disk | The interface for the app's own folders on its server: content, caches, generated files. | `files`, storage |
| files | The interface for user uploads, with owner scope, scanning and signed URLs. | disk, storage |
| system | The interface for facts about the server (user, hostname, platform, network interfaces) and the programs the app runs. | os, shell |
| discover | The `mainsdk discover` command: it reads the code and `main.yaml` and lists what the app uses. | scan, audit |
| schema | A description of app data built with `s` from `mainsdk/schema` (or any Standard Schema value): a type, a strict check and a JSON Schema. In `main.yaml`, `schema: 1` is the file's format version and `config.schema` is a JSON Schema file; say "format version" for the first. | validator, model (for data) |
| parser | A function from `mainsdk/parse` that turns raw text into a checked value: `parse.text`, `parse.number`, `parse.regex` and the others. A parser that finds nothing gives `MAIN-SCHEMA-0004`. | extractor (except `ai.extractor`) |
| issue (schema) | One place where a value fails a schema: `{ path, code, message }`, never the value. It is carried in the problem's `errors` member. Not a finding, which a check reports. | error, violation |
| manifest | The record `mainsdk discover --out` writes: every host, folder, fact, program and env var name the code uses, with file and line. It feeds `/.well-known/mainsdk.json` and the privacy labels. | `main.yaml` |
| seal | The signed record of one build: build hash, manifest, capability inventory, actions, interfaces, SBOM, check result, Main mark, commit and builder, served at `/.well-known/mainsdk.json` (ADR-0025). | signature, attestation (for the whole record) |
| build hash | `sha256:` over the sorted `mainsdk-build-hash/1` list of every shipped file; the seal's subject. | checksum, image digest |
| capability inventory | The seal's list of every MainSDK call the code makes, which are sensitive, and the `main.yaml` grants. | entitlements (that word is the app's plans) |
| app registry | The per-machine folder where each MainSDK app writes its seal and a heartbeat; `mainsdk apps` lists it. It describes apps, never people (ADR-0026). | inventory (that is Fleet's) |
| peer app | Another MainSDK app this one declares under `apps.peers`. Never an instance of the same app. | |
| app link | The opt-in local socket between two peer apps, opened with a mutual challenge on each app's sealed identity key. | channel (that is `realtime`'s) |
| instance | One running copy of an app: a process, container or serverless instance. | node, replica, peer |
| broadcast | A message one instance sends to every live instance of the same app with `events.broadcast()`; best effort, not durable. | realtime, pub/sub |
| realtime | The interface for live updates from the server to browsers and phones. | broadcast |
| channel | The name a browser subscribes to with `realtime`: `tenant`, `user:<id>` or `<prefix>:<id>`, always inside one tenant (ADR-0023). A broadcast has a topic, not a channel. A diagnostics channel is always named in full. | room, topic (for realtime) |
| diagnostics channel | A named, versioned stream on `node:diagnostics_channel` where MainSDK publishes each decision and side effect, such as `mainsdk:network.decision`, or a span such as `mainsdk:http.fetch` (ADR-0040). | hook, callback, event bus, channel (alone) |
| observer | A read-only function passed to `observe()` that receives events from diagnostics channels; it can never change a decision. Not observe mode, the `mode: observe` setting that logs a deny instead of enforcing it. | hook, listener, interceptor |
| chokepoint | The one SDK module allowed to reach a kind of outside resource: `network.ts` for `fetch`, TCP and UDP sockets, `system.ts` for disk, OS facts and programs, `workers.ts` for worker threads, cluster and forked processes (ADR-0040, ADR-0068). | |
| workflow | A multi-step flow written as one async function with `workflow()`, whose steps are journaled so it resumes after a crash (ADR-0022). Not a GitHub Actions workflow. | saga, pipeline, flow (for this) |
| run (workflow) | One execution of a workflow, with a `runId`, a state and a history. | instance, execution |
| step | One journaled unit of a workflow, written with `step(name, fn)`; once its result is journaled it never runs again. | task, activity |
| drain | What an app does on SIGTERM: stop taking work and let in-flight requests, jobs and steps finish within the deadline (ADR-0024). | graceful stop |
| SLO | A reliability target under `slo` in `main.yaml` (availability, `latency_p95`); its error budget is what's left before the target is missed. | SLA (for this) |
| pressure | The state of an instance whose CPU share, event-loop delay or memory has passed a `resources.pressure` threshold for the hold time; background work waits and health reports `degraded` (ADR-0053). | overload, stress, load (for this state) |
| shed | Answer a new request that isn't critical with 503 and `Retry-After` while the instance is past a `resources.shed` threshold. Not a rate limit, which counts calls under `limits`. | throttle, drop |
| query fingerprint | A query's text with every value replaced by `?`, hashed; slow and repeated queries are logged by it. | query hash, signature |
| trash | Where `delete` puts a record of a model with `db.models.<model>.trash`, restorable until the period ends. | soft delete (in prose), archive, recycle bin |
| row version | The integer `version` of a record on a model with `versions: true`, checked by `ifVersion`. | revision, ETag (for the stored value) |
| outbox | The table where side effects called on a transaction (`tx.jobs.run()`) wait until the commit, then are relayed. | queue (for this) |
| temporary folder | A private folder from `disk.temp()`, removed when the function settles. | scratch folder, tmp dir |
| flag | A feature switch evaluated with `flags.enabled()` or `flags.value()`, defined in config under `flags.<name>`. | toggle, feature gate |
| push (config) | A config value changed in the store while the app runs; a pushed `main.yaml` value may only tighten. Not a push notification, which is `notify.push()`. | deploy, override |
| tenant | One customer of your app whose data is kept apart from every other: an organisation or a personal tenant. Every record, file, key, log record and job belongs to one, read with `tenant.current()` (ADR-0021). | workspace, account, customer (for the data boundary) |
| organisation | A tenant that people join, with members, roles, teams, invites, domains and SSO; `kind: "org"` in code. | org (in prose), company, workspace |
| personal tenant | A tenant of one person, made at first sign-in when `tenancy.personal` is on, so B2C apps use the same API. | personal account |
| member | A person in a tenant, with roles in that tenant only. | seat (for the person), user (for the membership) |
| team | A named group of members inside one organisation, usable as an `access` subject. The Cloud plan is always "the Teams plan". | group (except a SCIM group) |
| Fleet tenant | An enterprise in MainSDK Fleet, with a `ten_…` id. Never shortened to tenant. | tenant (alone) |
| public route | The versioned HTTP route of an action, `<base>/v<major>/…`, listed in the OpenAPI document and the typed client (ADR-0027). The internal route `/api/actions/<name>` is not one. | endpoint (for the internal route) |
| API snapshot | The committed OpenAPI document that `mainsdk api diff` and `check` compare the app's API against. | contract (which is MainSDK's own, in TypeSpec) |
| imports | The interface for bringing data in from files and outside sources; plural because `import` is a reserved word (ADR-0028). | import (as the interface name) |
| import source | A driver behind `imports` that reads rows from an outside system: `rest`, `google-sheets`, `airtable`. | connector, integration |
| pull | One incremental read from an import source, from the tenant's cursor, on a schedule or with `imports.pull()`. | sync (that is `mainsdk sync`) |
| connection | One person's or one tenant's OAuth grant to one provider, with the scopes granted, held by `connections` (ADR-0029). | connector (a GRC link), integration, account link |
| step-up | A person's fresh approval before an app agent uses a scope listed under `step-up`; one approval covers one call. | re-consent |
| API key | A secret your app issues to one of its tenants with `apikeys.create()`, for calls from the tenant's own code; it carries scopes and is stored only as a digest (ADR-0019). | token, access key (for these) |
| scope (API key) | An `access` permission an API key may use, such as `orders.read`. | right, grant |
| plan | One of your app's offers to its customers, declared under `plans` in `main.yaml`, with features and limits. MainSDK's own Free, Teams and Fleet are "MainSDK plans". | tier, package |
| entitlements | The interface that answers what the current tenant's plan allows: `entitlements.has()`, `limit()` and `require()` (ADR-0020). Not `permissions`, which is what a server-side app may use on its machine. | capabilities, flags (for plan features) |
| cursor | The opaque `next` string a list call returns; pass it back as `cursor` to get the next page. | page token, offset |
| epoch | One state of an end-to-end encrypted group's keys; each membership change starts a new one. | generation, key version |
| sealed message | The ciphertext `e2e.encrypt` returns, which the server stores and can't read. | encrypted blob, envelope |
| seed | Synthetic demo data that `mainsdk seed` builds per tenant from the app's schemas; the same seed number gives the same rows, and it never holds real personal data (ADR-0030). | sample data, dump |
| fixture | Data a test creates with `app.fixtures()` from the same generator as `mainsdk seed`. | mock (for data), factory |
| preview environment | A short-lived database branch for one git branch, seeded when it is made and deleted with the branch (`mainsdk preview up`, `down`). | staging, sandbox (for this) |
| product event | Something a person did in the app, declared under `analytics.events` and recorded with `analytics.track()` (ADR-0031). Not a message sent with `events.publish()`. | event (alone, next to `events`), hit |
| metric | A counter, gauge or histogram declared under `analytics.metrics`. | stat, KPI (in code) |
| children's audience | People with an age band under 18, a `child` label, or everyone in an app with `users.audience: children` who isn't a known adult; their analytics are aggregate-only and their engagement messages strict. | minors, kids (in code) |
| journey | A durable workflow that reaches one person over days to bring them back, written with `journey()` and usually `ladder()` (ADR-0032). | campaign, drip, sequence |
| engagement message | A message sent to bring a person back, counted against the guardrails under `notify.engagement`. | nudge (in code), promo |
| guardrails (engagement) | The rules under `notify.engagement` that every engagement message obeys at run time: weekly limit, quiet hours, stop after ignored, strict rules for children. | frequency cap, throttle |
| guardian | The adult whom `access` relates to a child as `guardian_of`, who can pause and limit that child's engagement messages. | parent (in code) |
| index (search) | A declared collection of documents that `search` queries, under `search.indexes`, with one copy per region (ADR-0041). | collection, table (for this) |
| feed | The `feeds` interface, and what a person reads in it: items from the accounts they follow (ADR-0042). | stream, wall |
| timeline | One person's list of feed items, chronological or ranked, read with `feeds.timeline()`; it holds references to items, never copies. | news feed, inbox |
| fan-out | Writing a new item's reference into each follower's timeline (on write), or merging an author's items at read time (on read) above `fanout.threshold`. Not a broadcast between instances. | broadcast (for this) |
| trending | Windowed top-k counts of keys (tags, items) per region, with small counts hidden and no person stored. | hot, popular |
| report (moderation) | A person's flag on a piece of content or an account, with a reason, made with `moderate.report()`; reports on one target collapse into one case (ADR-0043). | flag, complaint |
| case | The unit a reviewer works in the moderation queue: one target, its reports, an assignee and a decision. | ticket, item (for this) |
| decision (moderation) | A reviewer's or the pre-screen's ruling on a case: remove, label, restrict, warn or none, with a ground. Not an access decision. | verdict, action (for this) |
| statement of reasons | The record sent to the author for every moderation decision: facts, ground, whether automated means were used, and how to appeal (DSA Art. 17). | notice |
| hold | The state of an upload, media output or item kept unreadable until the moderation pre-screen clears it. | quarantine (that is memory's and files' word) |
| rendition | One output of a video or audio at one size or bitrate, such as the 720p HLS stream, made by `media` (ADR-0044). | variant, flavour |
| memory | The interface that lets app agents remember the people they serve, inside one tenant and one app (ADR-0039). Never a driver name: an in-process driver is `local`. | knowledge base, vector store (for this), `memory` (as a driver) |
| memory (item) | One thing remembered with `memory.remember()`: a fact, preference, event, procedure, note or insight, with its source, valid time and trust. | record (for this), chunk, embedding |
| recall | Reading memories back with `memory.recall()` or, for a model, `memory.context()`; recalled text is always untrusted data. | retrieve, search (for memory) |
| forget | `memory.forget()`: a hard delete that cascades to insights and returns a signed receipt. Not `privacy.erase()`, which erases a person from every driver. | delete (for memory), soft delete |
| quarantine (memory) | The state of a memory written from a tool, MCP, the web or an import: returned only in its session until a person confirms it. | pending, unverified |
| run (agent) | One `ai.run()` loop: model turns and tool steps, bounded by steps, budget and time, ending with a stop reason (ADR-0062). | agent session, chain |
| handoff | Moving a run to another declared agent or to a person, keeping the memory scope of the person it acts for. | transfer, escalation (in code) |
| delegation | A child run started by an agent with a budget carved out of its own. | sub-agent (in code), spawn |
| part (prompt) | One image, document, audio or video item sent to a model inside a prompt, read through `files`. | attachment, blob |
| content credentials | The C2PA manifest MainSDK writes and signs with the app's own key on AI images and video (ADR-0055). | watermark |
| route (model) | A declared fallback chain of models under `ai.routes`, used as `route:<name>` (ADR-0063). | router, failover |
| response cache | The opt-in cache of model replies per feature, keyed by tenant and user. | semantic cache |
| sandbox | The interface that runs untrusted or AI-written code outside the app's process, through a driver (ADR-0059). | `eval`, VM, isolate |
| documents | The interface that reads PDFs, Office files and scans and renders PDFs (ADR-0058). | `pdf` (for reading), OCR service |
| eval set | The YAML cases for one AI feature that `mainsdk eval` runs and CI gates on. | test prompts, benchmark |
| voice session | One realtime conversation with a voice agent from `ai.voice.session()`, on a socket, a phone call or a room (ADR-0061). | call (unless it is a phone call) |
| draft (translation) | An AI-written message held as pending until a person approves it (ADR-0060). | machine translation (for this) |
| inbound protection | The secure headers, nonce-based CSP, CSRF checks, CORS allowlist, cookie flags and `security.txt` every server adapter applies from `inbound` in `main.yaml` (ADR-0033). | WAF, firewall (for this) |
| sanitize | `mainsdk/sanitize`: turning untrusted HTML or Markdown, from users or models, into safe HTML from an allowlist (ADR-0034). `sanitize.text` escapes. | purify, clean, strip |
| security event | One OCSF record, tagged with MITRE ATT&CK, about a decision the SDK made, in the stream under `security.events` (ADR-0035). A `high` or `critical` one also emits a signal, the live notice playbooks react to. | alert, event (alone) |
| detector | An in-process rule that turns repeated decisions into one security event: brute force, credential stuffing, access probing. | rule (that is a check rule or a policy) |
| door | A request path that bot defence scores: sign-in, sign-up, reset, WhatsApp codes, invites and forms declared under `bots.doors`. | endpoint, route (for this) |
| challenge (bots) | The proof-of-work a door asks a browser to solve before a request goes through. A CAPTCHA is one of its drivers. Not the wallet sign-in challenge. | CAPTCHA (for the built-in one) |
| step-up (sign-in) | A second sign-in method a risky sign-in must pass before its session is issued. Not the step-up approval of a connection. | MFA prompt |
| exfiltration guard | The in-process check on outbound calls and responses for secrets, labelled data and card numbers going where `main.yaml` doesn't declare (ADR-0037). | DLP |
| canary | A record or key planted in the app's own data or secrets that no real user touches; any touch is a critical security event. | honeypot (that is a form field), decoy |
| incident control | A kill switch, read-only mode or sign-out cut-off, pushed as `main.incident.*` (ADR-0036). | maintenance mode, panic button |
| kill switch | The incident control that refuses an action, route, interface, driver or app agent. | flag (for this) |
| overlap window | How long the previous value of a rotated secret still verifies. | grace period |
| share | A getqr.id link and QR code made with `share()`; the only way an app hands out a link, QR code or share page (ADR-0056). | short link, sharer |
| share link | The getqr.id URL of a share: private, expiring, read-only, with no personal data in it. | short URL, permalink |
| placement (share) | A kept getqr.id link and QR code for one place a campaign runs: a poster, a counter, a print insert or a creator. Not a policy placement. | spot, location |
| campaign (share) | A getqr.id container of placements, made with `share.campaigns.create()`. Never a journey. | journey, drip |
| deep link | A link from `links.create()` that opens a declared screen in the app, or on the web when the app isn't installed. | app link (that is the peer-app socket) |
| invite link | A link from `links.invite()` that lets a signed-in person join something, with uses and an expiry. Organisation invites are `auth.invites`. | invitation URL |
| sign-in link | A link from `links.signIn()` that signs a person in through the `link` method of `auth`. | magic link (in code and docs), passwordless link |
| TAPS | Trust Anchor Provenance System: HubXero Labs' open protocol for files that carry their own identity, provenance and policy, behind the `protect` interface (ADR-0064). | DRM, IRM |
| TAPS Node | The server that checks a protected file's policy and issues licences. MainSDK never runs one; the `local` driver fakes one in process. | node (alone), instance, key server |
| protected asset | A file put under TAPS with `protect()`, with an id `urn:taps:asset:…`; ciphertext without a licence. | protected file (in code), document |
| TAPS licence | Permission from a TAPS Node to open one version of a protected asset, short-lived and renewed every `protect.renew`. In code it is the `Licence` type of `protect`; TAPS's own spelling `license` stays only in TAPS names. Inside `protect` docs, licence alone means this. | license (in prose), token, grant, app licence (that is the `licence` interface) |
| app licence | A vendor's signed permission for an install or a tenant to use an app's features, verified offline by the `licence` interface (ADR-0070, [Licensing](https://mainsdk.dev/docs/concepts/licensing)). In code `licence`. Outside `protect`, licence alone means this. | license (in prose), licence key, activation code, entitlement (that is a plan check), TAPS licence |
| licensed feature | A feature name under `licence.features`: on only while the app licence in scope is valid or in grace and lists it. | paid feature, premium feature |
| root (licence) | A pinned Ed25519 key under `licence.roots` that signs issuing CA certificates and nothing else. | trust anchor (in prose), master key |
| issuing CA | The key that signs app licences and their revocation lists, certified by a root; rotated freely because every licence file carries its certificate. | intermediate, signing key (alone) |
| revocation list | A signed, numbered list of revoked or suspended licences (by revocation handle) or CAs; it never contains customers or licence ids. | CRL (in prose), blocklist |
| grace (licence) | The time after a licence expires, or after a received revocation, during which licensed features stay on and warnings are logged. Not the overlap window of a rotated secret, nor the grace of a past-due plan. | grace period (alone), buffer |
| network zone | An opaque id such as `z-7f3a` for a set of office or VPN addresses a protected asset may be opened from; the addresses stay in the tenant's encrypted zone table. | region (that is where data is stored), zone (alone), location |
| geo (protect) | The countries a protected asset may be opened from, with a minimum confidence, under `policy.geo`. | region (for this), location |
| release time | The `releaseAt` instant before which no licence is issued for an asset, for anyone. | embargo, unlock time |
| threshold release | A protected asset that opens only when `t` of its `n` named parties have released their key shares. | multi-sig, quorum (for this) |
| delegation (protect) | A person's signed, limited permission for an app agent to act on protected assets, never wider than the person. | grant (for this), impersonation |
| protection environment | The TAPS sealing service (`taps-seal`) that splits and time-locks keys for `releaseAt` and threshold assets. | seal (that is the build record) |
| Web Reader | The zero-install TAPS reader a `protect.share` link opens through getqr.id. | viewer app |
| TAPS ledger | The tamper-evident record of TAPS registrations, rules and opens, alongside MainSDK's decision log. | decision log (that is `log.audit`), blockchain |
| context | The one request context every interface reads: tenant, user, agent, trace, region, deadline and signal, held in one `AsyncLocalStorage` and carried into jobs, workflows and the outbox with `context.capture()` (ADR-0054). | request scope, session (for this) |
| signal | A typed, signed, short-lived `mainsdk-signal@1` message about the state of an app or its machine (`attack.suspected`, `pressure.high`, `key.rotated`), with severity, TTL and dedupe, emitted with `signals.emit()` or by the SDK (ADR-0069). Not a security event, which is the durable record; not a process signal such as SIGTERM, which is always named in full. | event (alone), alert (for this), message |
| scope (signal) | Where a signal reaches: `instance` (this process), `app` (every instance, through broadcast) or `host` (neighbour apps on this machine). | range, level |
| trust (signal) | How a received signal was verified: `self`, `app` (another instance), `peer` (a declared peer app's identity key) or `host` (the per-host key only). | origin, source (for this) |
| norm | What normal looks like for one metric in one time bucket, learned by `norms` from the app's own numbers with no model. Not the Main 27 baseline. | baseline (that is Main 27), profile, model (alone) |
| anomaly | A metric outside its norm for `hold` windows in a row, reported as an `anomaly.detected` signal with a score. | outlier, alert (for this) |
| playbook | A rule in `main.yaml` under `playbooks` that runs declared steps when a signal arrives, with dry-run, approval and rollback (ADR-0069). Not a recipe, which edits code. | runbook (that is a document for people), automation, hook |
| step (playbook) | One reaction from the closed list (`limits.tighten`, `flags.disable`, `jobs.pause`, `posture.raise` and the rest) or an action marked `reaction: true`. Not a workflow step. | action (unless it is one), task |
| run (playbook) | One execution of a playbook rule, with its trigger, steps, approval, state and rollback, read with `playbooks.get()`. | incident, execution |
| reaction overlay | The in-memory, expiring, tighten-only layer a playbook writes over pushed and declared config; removing an entry restores the value. | override, patch (for this) |
| posture | The app's defence level, `normal`, `guarded`, `high` or `lockdown`, raised by a playbook step and lowered only by expiry or a person. | threat level, mode (for this) |
| guard (playbooks) | The one check every playbook run passes: blast radius, rate, loops, tenancy and the never-a-reaction list (spec reaction-safety). | safety net, firewall |
| neighbour | Another MainSDK app on the same machine and OS user with `neighbours.host: on`, heard over the host bus. A neighbour that both apps declare under `apps.peers` is also a peer app. | sibling, peer (alone) |
| host bus | The user-only sockets through which neighbours send and receive host-scope signals, authenticated by the per-host key. | broker, daemon, channel (for this) |
| ask (neighbour) | One of the three requests a peer app may make of another: `status`, `posture.raise` or `load.shed`. Never code, data or a lowered guard. | command, RPC, negotiation |
| advisor | The optional model that proposes one of the app's declared playbooks with a reason a person approves; off by default (spec advisor). | AI operator, autopilot |
| operate surface | The app's MCP tools for agents (`ops.status`, `ops.plan`, `ops.run` and the rest) on a user-only socket and loopback, served through `mainsdk ops mcp` (spec ops-mcp). | admin API, backdoor |
| shared context | Consent-gated, first-party events and attributes about a person that peer apps of one owner share on one machine under a declared purpose, with `context.shared` (ADR-0071). Not the request context. | tracking, profile, user graph |
| context id | The `cx_` id that links one person's shared context across a group's apps, from the signed-in subject or a resettable random id, per tenant; never an advertising or device id. | user id (for this), device id, advertising id |
| context group | The named set of peer apps of one owner that share context, declared as `context.group`. | family, cluster |
| runtime store | The one store the SDK keeps its own shared state in (limits, meter, idempotency records, caches, leases), set under `runtime.store` as `local`, `redis` or `db` (ADR-0054). | cache, KV (for this) |
| local driver | The driver with id `local` that every interface has: no account, key or network, used by `mainsdk dev` and `createTestApp()`. Never named `memory`, `file` or `fake`. | memory driver, fake driver, dev driver |
| domain verb | A call verb beyond the standard nine (`create`, `get`, `list`, `update`, `delete`, `watch`, `remove`, `revoke`, `erase`) and `on`, such as `send` or `charge`, listed under the interface's `verbs` in the catalog. | |
| error area | The one `MAIN-<AREA>` prefix an interface's own codes use, named in the catalog; shared conditions use `MAIN-SDK`. | error family (for this) |
| template | A runnable starter app with code, `main.yaml` and tests, started with `mainsdk init --template saas`, `agent` or `social`. Not a preset, which only writes `main.yaml`. | starter, boilerplate, example app |
| recipe | A task-level change applied with `mainsdk add recipe <name>` that edits code, `main.yaml`, tests and docs together. An eject recipe is a different thing: the codemod `mainsdk eject` runs. Not a playbook, which reacts to signals. | generator |
| machine fix | The patch on a finding (a unified diff, a `main.yaml` JSON Patch, or both) that `mainsdk fix` applies; the `fix` text explains it. | autofix, quick fix |
| cockpit | The local page `mainsdk dev --cockpit` serves on `127.0.0.1`: what the app uses, live decisions, events, traces and local replay. | dashboard, console (that is MainSDK Cloud's) |
| fix-up round | In the agent benchmark, one turn after the agent says it's done in which it gets only the names of failing hidden tests; at most three. | retry, iteration (for this) |
| socket | A two-way WebSocket connection to `realtime` from one browser or phone, authorised before it opens; it carries channel events, client messages and binary streams (ADR-0048). A TCP connection or a UDP socket is always named in full. | room, connection (alone) |
| client message | A JSON message a browser sends on a channel over a socket, accepted only where the channel's prefix declares a `send` action and handled with `realtime.on()`. | inbound event, RPC |
| binary stream | A numbered stream of bytes inside a socket, opened on a channel with a declared content type and byte budget, such as live audio. It never leaves the instance that holds the socket. | track, pipe (for this) |
| high-water mark | The queued bytes on a binary stream above which its producer waits; past the socket's `buffer` the socket is closed. | buffer size (for this) |
| voice owner | The person whose voice a cloned voice copies. Only they can consent to the clone, and withdrawing that consent deletes it (ADR-0049). | speaker, voice actor (for this) |
| disclosure (AI output) | The machine-readable `ai-generated` metadata every piece of AI audio carries in its container, or as the first event on a raw stream. | watermark (unless a provider declares one) |
| usage record | One idempotent `meter.record()` entry: a metric, a value, a tenant and optional API key, feature and user. A billing fact, not a product event (ADR-0050). | usage event, hit |
| policy (limits) | A named rate limit, quota or concurrency rule under `limits`, with its key and its `on-store-down` mode. Not a Cedar policy, which `policy` and `access` evaluate. | rule, throttle |
| quota | A ceiling on how much one key may use in a window, checked with `limits.quota()`. A ceiling set by the tenant's plan is a plan limit under `plans.<name>.limits`. | allowance, cap |
| on-store-down | The mode a policy declares for when its store is down or slow: `open`, `closed` or `local` (ADR-0050). | fail mode, fallback |
| compute job | One run of a compute target on a provider, driven by the built-in workflow `mainsdk.compute` (ADR-0051). Not a `jobs.run` job. | task, prediction (for this) |
| target (compute) | A declared, pinned model version or function under `compute.targets`, with its driver, region, timeout and price. | model, endpoint (for this) |
| mail | The interface that receives email through a provider's inbound webhook and keeps mailboxes, threads and attachments (ADR-0052). Sending is `email`. | inbox (for the interface), email (for receiving) |
| mailbox | A named address with its folders in `mail`, owned by a person or a tenant; also a person's existing mailbox pulled with a connection. | inbox (for the whole mailbox), account |
| pull (mailbox) | One incremental read of a connected mailbox over IMAP or JMAP, from its cursor. | sync |
| preset (provider) | A built-in set of endpoints or signature rules for one provider, chosen with `preset:` under `connections.providers` or `webhooks.inbound`. Not a `main.yaml` preset chosen at `init`. | template (for this) |
| inbound endpoint | A path the app serves for one provider's webhooks, declared under `webhooks.inbound` and listed by `discover` and the seal. | hook URL, listener |
| customer endpoint | An outbound webhook URL one tenant adds with `webhooks.endpoints.create()`, with its own secret, delivery log and disable rule. | subscriber, callback URL |
| occurrence | One dated repeat of a recurring calendar event, named by its original start; an override changes one occurrence. | instance, recurrence (for this) |
| happy path | The shortest correct use of an interface: at most three call lines that run on the `local` driver with no config, kept in the catalog's `happy:` and shown first on its page (ADR-0067). | hello world, basic usage |
| five-minute test | The `tools/e2e` stage that goes from an empty folder to sign-in, a database and a protected route in 4 commands and 12 lines of app code (spec design-language). | quick start (for the test) |
| fix (of a problem or finding) | The one sentence in a problem or finding that says what to do, starting with a verb, such as "Add api.ipinfo.io to network.allow in main.yaml." | hint, suggestion, remedy |
| snapshot (CLI) | The exact text a CLI command prints for a fixture, kept in `packages/cli/test/snapshots/` and equal to its sample in spec design-language. | golden file, fixture (for this) |
| dev sign-in | The `dev_<name>` bearer token `mainsdk dev` prints, accepted by the `local` auth driver from loopback only, never in `env: prod`. | test login, backdoor |
| net | The interface for raw TCP and UDP: `net.connect`, `net.listen` and `net.udp`, checked against `network` in `main.yaml` (ADR-0068). `network` stays the `main.yaml` section and the HTTP layer. | sockets (for the interface), raw network |
| socket entry | A `network.allow` entry with a protocol and ports, `tcp://db.acme.dev:5432` or `udp://8.8.8.8:53`. A plain entry (a host, IP or range) covers HTTP, HTTPS and WebSocket only. | rule (alone), port rule |
| listen entry | An entry under `network.listen` that lets the app accept TCP connections or bind UDP on a port, `tcp:7000` or `tcp:9000-9010@0.0.0.0`; loopback unless it names a bind address. | inbound rule, port grant |
| TCP connection | One TCP stream from `net.connect` or accepted by `net.listen`, read and written as Web streams. Always said in full: a connection alone is an OAuth grant, a socket alone is `realtime`'s. | socket (alone), connection (alone) |
| TCP server | What `net.listen` returns: a listener on one declared port that runs a handler per TCP connection. | listener (alone), socket server |
| UDP socket | A bound UDP endpoint from `net.udp()` that sends and receives datagrams. Always said in full. | socket (alone), datagram channel |
| half-open | A TCP connection where one side has sent FIN and the other may still write; off by default, `halfOpen: true` keeps it. | half-closed |
| worker thread | A thread from a worker pool that runs worker modules; not a job worker or a workflow worker, which claim queued work on the main thread. | thread (alone), web worker |
| worker pool | The threads, or processes with `isolation: process`, that run one set of worker modules, sized from the cores the process may use. The built-in pool runs MainSDK's own modules. | thread pool (for this), executor |
| worker module | A file whose default export is `worker(fn)`, run with `workers.run` and declared under `workers.modules`. | worker script, task file |
| worker task | One `workers.run` call on a worker pool, with its own timeout and signal. Not a job (`jobs.run`) or a step. | job, step (for this) |
| cluster | One instance per core on one host, sharing a listening port, started with `cluster.run` and declared under `cluster` (ADR-0068). | fleet, cluster of machines |
| primary (cluster) | The process `cluster.run` forks instances from. It serves no requests; it supervises, rolls restarts and relays the `local` store and broadcasts. | master, parent (for this) |
| cores | The CPUs the process may use: `os.availableParallelism()` capped by the cgroup CPU quota; pools and `cluster.processes: auto` are sized from it. | CPUs (for this), vCPUs |
| cache | The interface that memoises calls under keys carrying the tenant and region, with the rules that keep personal responses out of shared caches (ADR-0073, spec http-cache). Not `kv`, where you set and read values yourself. | memo, kv (for this) |
| credentialed request | A request with the session cookie, an `Authorization` header or the API key header, or whose response sets a cookie; its response is never shared-cacheable. | authenticated request (for the cache rule) |
| auth routes | The `/_mainsdk/auth/*` routes every server adapter mounts for the browser client: session, passkeys, link, WhatsApp, step-up, switch and sign-out (spec auth-client). | auth API, auth endpoints |
| deploy config | The platform files `mainsdk deploy config` writes from `main.yaml`: `vercel.json`, `wrangler.toml`, `fly.toml`, a `Dockerfile`. MainSDK never deploys or hosts (ADR-0072). | deployment (for the files), deploy manifest |
| preflight | `mainsdk deploy preflight`: the step in the platform build that checks required env var names, regions and `check --env` before anything ships. | pre-deploy hook |
| tick | The signed `POST /_mainsdk/jobs/tick` a serverless platform's cron sends to run one declared schedule once per slot. | cron job (for the request), heartbeat |
| error group | Every captured error with one fingerprint, counted per release (spec error-reporting). | issue (that is GitHub's, or a schema's) |
| fingerprint (error) | The 16-hex hash of an error's code or name and its first three in-app frames, stable across line moves, machines and restarts. Not a query fingerprint. | signature, error hash |
| upgrade notes | The `upgrade/<version>.json` file each CLI release ships, listing breaking changes with their codemods, manual steps and `main.yaml` moves (spec upgrade). | changelog (for this file) |
| deps gate | The `mainsdk check` gate that reads the lockfile for made-up, brand-new and look-alike packages, advisories, licences and install scripts (ADR-0074). | SCA, audit (for this) |
| connected device | A machine, IoT thing, AI agent runtime or edge service that enrols with your app through `mainsdk/device`, known by the `did:key` of a key it made itself and a `dvc_` id (ADR-0076). Not a person's signed-in device, which is `auth.devices`. | endpoint, agent, node, asset (for this) |
| device client | The program on a connected device that talks to your app through `mainsdk/device/client`. | agent, daemon, sensor (for this) |
| enrolment | A device joining one tenant of your app with a proof: an enrolment token, a code a person approves, a workload OIDC token or attested evidence (spec device-identity). | registration, onboarding, provisioning |
| device credential | The short-lived statement the device authority signs that binds a device's key to its tenant and attestation level; the heartbeat renews it. | device certificate, device token |
| device authority | The app's key, or its TAPS DID, that signs device credentials, policy bundles and commands. | CA, root (for this) |
| attestation level | `none`, `software`, `hardware` or `environment`: what the server's appraisal of a device's evidence showed (spec device-attest). | trust score, posture (for this) |
| telemetry stream | A named kind of record devices send, declared under `device.telemetry.streams` and described with `s`; what it holds is the builder's. | topic, channel, event type (for this) |
| policy bundle | One signed, versioned document of device settings published to a tenant or a group (spec device-policy). Not the `policy` interface, which decides permissions. | config push, profile |
| device command | A signed request for a connected device to run one handler it registered, with an expiry and approvals, answered by a signed receipt (spec device-commands). | job, task, remote action, RPC (for this) |
| heartbeat (device) | The signed message a connected device sends every interval with its versions, policy, clock and pressure (spec device-health). Not the app registry's heartbeat or a jobs tick. | ping, check-in |

## Words we avoid

- **plugin, module, extension** for a driver or an interface. A Tauri plugin or an Expo config plugin is a third party's own word and stays, and a module is the unit `mainsdk adopt` moves one at a time.
- **scan, lint** for the check. A check is one command, `mainsdk check`. (`mainsdk adopt scan` and the scan of an uploaded file are different things and keep their names.)
- **manifest** or **config file** for `main.yaml`. The manifest is what `mainsdk discover` writes from the code; `main.yaml` is what you declare.
- **files** or **storage** for `disk`. `files` is user uploads; `disk` is the app's own folders.
- **AI agent** on its own. Say coding agent or app agent, because they do different jobs.
- **vendor** for a provider.
- **sync** for reading from an import source. That is a pull; `mainsdk sync` is a CLI command.
- **connector** for a person's OAuth grant. That is a connection; a connector links to a GRC tool.
- **cap** for a limit. A frequency cap on reminders is the weekly limit, `notify.engagement.max-per-week`.
- **event** on its own for something a person did. Say product event; an event without the word is a message on `events`.
- **campaign** or **drip** for a journey. Marketing broadcasts are `email.marketing` and staged rollout.
- **broadcast** for updates sent to browsers or phones. Those are `realtime`; a broadcast goes only between instances of one app (ADR-0017).
- **hook** or **callback** for an observer, and a bare **channel** for a diagnostics channel. Observers only watch; nothing in MainSDK lets app code intercept a decision.
- **node**, **replica** or **peer** for an instance. Instances never link to each other; they share a store. A peer app is a different app, declared under `apps.peers`.
- **DLP** for the exfiltration guard, **WAF** for inbound protection, and **CAPTCHA** for the built-in bot challenge. DLP and WAF are product categories MainSDK doesn't sell; a CAPTCHA is one driver of the challenge.
- **mail** for sending. Sending is `email`; `mail` receives and keeps mailboxes. And no **SMTP server** for anything MainSDK runs: inbound mail comes through a provider's webhook (ADR-0052).
- **watermark** for the disclosure metadata MainSDK writes on AI audio. Only a watermark a provider declares is called one (ADR-0049).
- **phase** in a timeline. Say the milestone: `0.3`. Phases are only the five roadmap stages.
- **short link** for a share link, **app link** for a deep link and **magic link** for a sign-in link. An app link is the socket between peer apps; a getqr.id campaign is never a journey (ADR-0056).
- **endpoint** or **agent** for a connected device, and **EDR** or **antivirus** for anything MainSDK ships. Those are products customers build on the device plumbing; MainSDK carries no detection content (ADR-0076).
- **memory** as a driver name. `memory` is the agent memory interface; an in-process driver for tests is `local` (ADR-0039). "In-memory fake" for the testing kit stays.
- **core**, **binding** or **shared core** for a language SDK. Every language SDK is its own library; languages share the contract layer, never code (ADR-0075). The TypeScript core is the code inside the npm package.
- **simply, just, easy, seamless, magic, powerful, blazing** in docs prose. Show the command or the code instead (ADR-0067).

## Status words

| Say | It means |
| --- | --- |
| Planned for 0.N | Specified, not built; ships at milestone 0.N. |
| Building | In progress in a milestone. |
| Preview | Usable, and may still change. |
| Beta | Feature-complete; the contract may still change before 1.0. |
| Stable | The contract is frozen for the major version. |
| Pre-release | No package is published yet. The docs describe the planned product. |

Every term has a one-line definition in the [glossary](https://mainsdk.dev/docs/reference/glossary). A new term is added to both in the pull request that first uses it (ADR-0012).