Glossary
One-line definitions of the terms MainSDK uses, from action and adapter to TUF and workspace, each linked to the page that explains it.
Terms you meet in these docs, one line each. Follow the link for the full story. For which word to use and which to avoid, see the words we use.
Start with these three
These are the only ideas you need for the thirty-minute path.
| Term | Meaning |
|---|---|
| Cluster | One instance of the app per core on one shared port, started by cluster.run and declared under cluster in main.yaml; the primary forks and supervises and never serves a request. Workers and cluster |
| Interface | One standard way to do a job, such as auth, db or ai; your code calls it, never the provider. Interfaces and drivers |
| Driver | The provider behind an interface, such as resend for email; a local one needs no account or key in development, and you swap it by editing one line in main.yaml. Interfaces and drivers |
| Check | mainsdk check: it reads your project, fails on mistakes such as a key in code, and names the fix for each one. The check |
| Worker module | A file that matches workers.modules and has a default export made with worker(fn); workers.run runs it on a thread or process and only declared modules run. Workers and cluster |
| Worker pool | The threads, or child processes with isolation: process, that run worker modules: started on demand up to size, ended when idle, with a bounded queue. Workers and cluster |
All terms
Alphabetical.
| Term | Meaning |
|---|---|
main.lock | The generated, committed file that pins each driver version with its hash, one per workspace. Contracts and versioning |
main.yaml | The file that declares what your app is, needs and may do. main.yaml |
mainsdk mcp | The local MCP server for coding agents: catalog lookup, check, discover, explain, next, fix and seal diff as tools (planned for 0.4). Not the MCP server for your own actions. MCP |
mainsdk next | The one inner-loop command: it runs check, types, the affected tests and scenarios and returns one next action (planned for 0.4). Repair loop |
| Action | App logic written once with action() that becomes an endpoint, a server action, a CLI command and, if you mark it, an MCP tool. Actions and MCP |
| Adapter | The one import that wires MainSDK into your framework: Next.js, Hono, Express, workers, Prisma or Drizzle. How it works |
| Adopt | Bringing an existing app onto MainSDK step by step with mainsdk adopt. Adopt an existing app |
| Advisor | The optional model that reads signals and norms and proposes one of your declared playbooks with a reason you approve; off by default (planned for 0.6). Connected intelligence |
| Agent benchmark | The published test in which the same coding agent builds three apps with and without MainSDK, reporting median tokens, time, fix-up rounds, tests passed and security defects (planned for 0.5). Agents |
| Anomaly | A metric outside what is normal for that hour of the week for several windows in a row, reported as an anomaly.detected signal (planned for 0.4). Connected intelligence |
| API key | A secret your app issues to one of its tenants with apikeys.create(), shown once and stored only as a SHA-256 digest; it carries scopes, can be rotated and revoked, and sets the tenant when apikeys.verify() accepts it (planned for 0.3). apikeys |
| API snapshot | The committed OpenAPI document of your app's public routes (api.snapshot, api/openapi.json by default); mainsdk api diff fails on a breaking change against it and check flags it when stale (planned for 0.3). action |
| App agent | An agent that runs inside your app and acts for a user, such as a support bot; it has a name under agents in main.yaml, a budget and approvals. Not a coding agent. Agents with an identity, a budget and approvals |
| App link | The opt-in local socket between two peer apps on one machine, opened only after each proves its identity with its sealed key; off by default. mainsdk CLI |
| App registry | The folder on a machine (~/.mainsdk/apps) where each MainSDK app writes its seal and a heartbeat; mainsdk apps lists it, and it describes apps, never people. mainsdk CLI |
| Attestation level | What a connected device has shown about itself: none, software, hardware or environment; a level that is not refreshed in time drops to none (planned for 1.3). Connected devices |
| Audit log | The append-only, tamper-evident record of every decision and sensitive action. log |
| Auth routes | The /_mainsdk/auth/* routes every server adapter mounts so the browser client can sign people in, step up, switch organisation and sign out (planned for 0.4). auth |
| Baseline | The named, versioned minimum every MainSDK app meets; the current one is Main 27. Main 27 |
| Binary stream | A numbered stream of bytes inside a realtime socket, opened on a channel with a declared content type and byte budget, such as live audio; it stays on the instance that holds the socket (planned for 0.4). realtime |
| Broadcast | A small message one instance of your app sends to every live instance of the same app with events.broadcast(), for cache invalidation and "config changed" nudges; best effort, size limited and not durable. Not updates to browsers or phones, which are realtime. jobs |
| Budget | The spend and call allowance of one app agent, set under agents.<name>.budget (for example { spend: $5/day, calls: 500/day }) and checked before each call; a person approves destructive or costly steps. A user, feature or app has a limit, not a budget. Agents with an identity, a budget and approvals |
| Build hash | The sha256: hash over the sorted list of every file a build ships, with each file's own hash and size; the thing the seal signs. mainsdk CLI |
| Build id | The label of one release under updates.build, published at /_mainsdk/updates/build; an open browser tab loaded from another build is stale and offered a reload. updates |
| Cache | The interface that memoises calls under keys carrying the tenant and region, keeps personal responses out of shared caches and keeps serving when its store is down (planned for 0.4). cache |
| Calendar | The interface for events with RFC 5545 recurrence in IANA time zones, iCalendar import and export, and free/busy (planned for 1.2). calendar |
| Campaign (share) | A getqr.id container of placement links, made with share.campaigns.create(); never a journey (planned for 0.3). share |
| Canary | A record or key planted in your app's own data or secrets that no real user touches, in a canary tenant per region; any touch is a critical security event, and the reader isn't tipped off (planned for 0.4). Security model |
| Capability inventory | The seal's list of every MainSDK call the code makes, which ones are sensitive (network, disk, programs, cross-tenant, payments, AI spend, destructive actions) and what main.yaml grants. mainsdk CLI |
| Capability profile | What a driver declares it supports, such as relations or attachments; check names any gap. Drivers and conformance |
| Case | The unit of work in the moderation queue: one target, its reports counted by reason, an assignee and, at the end, a decision (planned for 0.4). moderate |
| Challenge (bots) | The invisible proof-of-work a door asks a browser to solve before a risky request goes through; Turnstile and hCaptcha are optional drivers. Not the wallet sign-in challenge (planned for 0.3). limits |
| Challenge (wallet sign-in) | A single-use message your app asks a wallet to sign to prove who the user is; it expires in five minutes or less and creates the same session as any other sign-in method. auth |
| Channel | The name a browser subscribes to with realtime: tenant, user:<id> or a declared prefix such as order:42; always inside one tenant, and every subscribe is checked by access (planned for 0.3). A broadcast has a topic, not a channel. realtime |
| Check | mainsdk check: every gate, run locally and in CI, exiting 0, 1 or 2. The check |
| 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 follow the strict rules (planned for 0.3). analytics |
| Chokepoint | The single path every sensitive call takes, so check can block raw database clients, raw fetch and direct provider SDKs. Security model |
| Circuit breaker | The per-host switch in the network layer that stops calls to a failing host for a cooldown and fails them fast with MAIN-NET-0010; set under network.http.breaker. network |
| Client message | A JSON message a browser sends on a channel over a socket, accepted only where the channel declares a send action, handled with realtime.on() (planned for 0.4). realtime |
| Cluster | One instance of your app per core on one host, sharing a listening port, started with cluster.run and declared under cluster; the primary supervises, rolls restarts through the drain and relays the local store and broadcasts (planned for 0.4). workers |
| Cockpit | The local page mainsdk dev --cockpit serves on 127.0.0.1 with what the app uses, live decisions, events, traces and local replay (planned for 0.4). mainsdk CLI |
| Codemod | A small script in the CLI that rewrites your source for one breaking change of a release, run by mainsdk upgrade on your own TypeScript compiler and safe to run twice. Upgrades |
| Coding agent | An AI that writes your code, such as Claude Code, Cursor or Codex; it follows the skill and runs mainsdk check --json --agent. Build with agents |
| Compute job | One run of a compute target on Modal, Replicate, RunPod or a local program, driven by a built-in workflow with heartbeat, progress, cancel and a cost limit; MainSDK never hosts the model (planned for 0.6). compute |
| Confirmshaming | Opt-out copy that guilts the person for saying no ("No thanks, I don't want to learn"); mainsdk check reports it as MAIN-ENGAGE-0010. notify |
| Conformance suite | The tests every driver passes for each interface version it claims. Not the parity vectors, which compare language SDKs. Drivers and conformance |
| Connected device | A machine, IoT thing, AI agent runtime or edge service that enrols with your app through the optional mainsdk/device interface and signs everything it sends with a key it made (planned for 1.3). Connected devices |
| Connection | One person's or one tenant's OAuth grant to a provider such as GitHub or Gmail, with the scopes granted, held by connections; tokens are sealed, sent only to the provider's hosts, and an app agent uses only the scopes agents.<name>.connections gives it (planned for 0.3). Agents |
| Consent record | The stored proof that a person opted in to SMS or WhatsApp for one phone number, with when and where they agreed; notify skips the channel without it (MAIN-NOTIFY-0003, MAIN-NOTIFY-0004). Notifications |
| Content credentials | The C2PA manifest signed with the app's own key that marks an image or video as AI generated, kept through media transforms (planned for 0.4). ai |
| Context | The one request context every interface reads (tenant, user, agent, trace, region, deadline, signal), carried into jobs and workflows (planned for 0.3). How it works |
| Context id | The cx_ id that links one person's shared context across a group's apps, from their sign-in or a resettable random id; never an advertising or device id (planned for 0.4). Connected intelligence |
| Contract | A versioned definition of a boundary, such as email@1.4 or main.yaml schema: 1, written once in TypeSpec. Contracts and versioning |
| Contract layer | What every language SDK shares, as data only: the TypeSpec contracts and their wire formats, the main.yaml schema, the error and finding codes and the parity vectors. Never code. Core and language SDKs |
| Cores | The CPUs your process may use: os.availableParallelism() capped by the container's CPU quota; worker pools and cluster.processes: auto are sized from it (planned for 0.4). workers |
| Credentialed request | A request with a session cookie, an Authorization header or an API key, or whose response sets a cookie; its response always goes out private, no-store unless you choose a private policy (planned for 0.4). cache |
| Cursor | The opaque next string a list call returns; pass it back as cursor for the next page. It is bound to the query, tenant and user that made it and expires after 24 hours (planned for 0.3). db |
| Customer endpoint | An outbound webhook URL one tenant adds with webhooks.endpoints.create(), with its own secret, rotation, delivery log and automatic disable after sustained failures (planned for 0.3). webhooks |
| Data label | The kind of data a field holds: personal, sensitive, child, phi or pan (always refused). Data and regions |
| Device authority | The Ed25519 key, held as a secret, that signs device credentials, policy and commands; two keys may be listed so one can be rolled over (planned for 1.3). Connected devices |
| Device credential | A short-lived signed document your app's authority key gives a connected device, naming its key, tenant and attestation level; the device renews it with its own key (planned for 1.3). Connected devices |
| Generated block | The lines of a deploy file between # mainsdk:generated:begin and # mainsdk:generated:end (in vercel.json, the keys regions, crons and buildCommand), which mainsdk deploy config owns and mainsdk check keeps true (MAIN-DEPLOY-0010). Deploy config |
| Heartbeat (device) | The signed report a connected device sends every interval: its versions, resources and buffer; missed ones make it late and then silent (planned for 1.3). Connected devices |
| Link placeholder | {{link.<name>}} in an engagement message: a link declared under notify.engagement.links and minted through share once per journey, rung and variant, never per person. engagement |
| Look-alike package | A direct dependency whose name is one edit from a popular npm package it is not, reported as MAIN-DEPS-0003 because a mistyped or squatted name installs someone else's code. Dependency checks |
| Preflight | mainsdk deploy preflight --env <env>, run in the platform build: it fails the build when a required env var name is missing, a region breaks the data regions or mainsdk check fails. Deploy config |
| Stop handle | A keyed hash that names a person in a push stop action or an email one-click unsubscribe, so the stop works without an id or address in the message; engagement.stopByHandle resolves it. engagement |
| Tick | The platform cron's call to POST /_mainsdk/jobs/tick?schedule=<name> that wakes a schedule on a serverless target; each schedule runs once per slot. Deploy config |
| Deadline | The longest one outbound call may take across all its attempts and waits, set under network.http.retries.deadline. Not a budget, which belongs to an app agent. network |
| Decision | The allow or deny the policy engine returns for one call, with its policy version and mode. Policy |
| Decision (moderation) | A ruling on a moderation case (remove, label, restrict, warn or none) with the terms clause or law it rests on; each one gets a statement of reasons and can be appealed once to a different reviewer (planned for 0.4). moderate |
| Declared public caching | http: { cache: { scope: "public", maxAge } } on a plain read action: the only way a response is shared-cacheable. It is refused at run time if the action reads a session, an API key or the tenant (MAIN-CACHE-0002). Cache |
| Deep link | A link from links.create() that opens a declared screen in the app on Android or iOS, or on the web when the app isn't installed; it grants nothing (planned for 0.4). links |
| Delegation | A child ai.run an agent starts with a budget carved out of its own; the child's spend counts against the parent (planned for 0.4). ai |
| Delegation (protect) | A person's signed, limited permission for an app agent to act on protected assets, never wider than the person and revocable at once (planned for 0.4). protect |
| Deploy config | The platform files mainsdk deploy config writes from main.yaml (vercel.json, wrangler.toml, fly.toml, Dockerfile); MainSDK never deploys or hosts your app (planned for 0.4). Deploy on Vercel |
| Deps gate | The mainsdk check gate that reads your lockfile for made-up, brand-new and look-alike packages, known advisories, licences and install scripts (planned for 0.5). The check |
| Detector | An in-process rule that turns repeated decisions into one security event: brute force, credential stuffing or access probing; it reports and never blocks on its own. Security events |
| Dev sign-in | The dev_<name> bearer token mainsdk dev prints so you can call a protected route as a test user; accepted from loopback only, never in production (planned for 0.3). CLI |
| Device command | A signed request for a connected device to run one handler it registered, with an expiry, approvals and a signed receipt (planned for 1.4). Connected devices |
| Diagnostics channel | A named, versioned stream such as mainsdk:network.decision on Node's node:diagnostics_channel, where MainSDK publishes each decision and side effect, redacted; read it with observe() (planned for 0.3). log |
| 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 (planned for 0.4). ai |
| Discover | The mainsdk discover command: it reads the code and main.yaml and lists what the app uses. Declare what your app uses |
| Disk | The interface for the app's own folders on its server: content, caches, generated files. Declared under permissions.disk. disk |
| DLT template | An SMS template registered with the carriers in India, set as dlt-template-id; SMS to a +91 number is skipped without one (MAIN-NOTIFY-0005). Notifications |
| Documents | The interface that reads PDFs, Office files and scans into text, tables and layout, and renders PDFs (planned for 0.4). documents |
| Domain verb | A call verb beyond the standard ones (create, get, list, update, delete, watch, remove, revoke, erase, on), such as send, declared in the catalog (planned for 0.3). Interfaces and drivers |
| Door | A request path bot defence scores: sign-in, sign-up, password reset, WhatsApp codes, invites and forms you declare under bots.doors (planned for 0.3). limits |
| Drain | What your app does on SIGTERM: report not ready, stop taking work, let in-flight requests, jobs and workflow steps finish within health.shutdown.deadline, then flush logs and the audit log (planned for 0.4). Health and status |
| Driver | The code that talks to one provider behind an interface, such as resend for email, picked in main.yaml. Interfaces and drivers |
| Engagement message | A message sent to bring a person back, from a journey or an engagement category; it counts against the guardrails under notify.engagement: a weekly limit, quiet hours and a stop after a run of ignored messages, and every one carries a one-step stop for its category. engagement |
| Enrolment (device) | A connected device joining one tenant of your app with a one-time token, a code a person approves, a workload OIDC token or attested evidence (planned for 1.3). Connected devices |
| Entitlements | The interface that answers what the current tenant's plan allows: entitlements.has("export"), entitlements.limit("seats") and entitlements.require(), which fails with 403 and an upgrade hint (planned for 0.3). Not permissions. entitlements |
| Epoch | One state of an end-to-end encrypted group's keys. Each time a member is added or removed the group moves to a new epoch with a fresh secret that only the new members hold, so a removed member can't read anything sealed afterwards. End-to-end encryption |
| Erasure record | What privacy.erase returns: each driver and its confirmation, signed by the project key. It holds a keyed pseudonym of the person, never their id. A driver that never confirms makes it partial. Privacy and data rights |
| Error area | The one MAIN-<AREA> prefix an interface uses for its own codes; conditions every interface shares use MAIN-SDK (planned for 0.3). Errors |
| Error budget | How much failure an SLO allows, such as 0.1% of requests for availability: 99.9%; the burn rate is how fast it is being used, and a fast burn is logged with MAIN-HEALTH-0010 (planned for 0.4). Health and status |
| Error group | Every captured error with one fingerprint, counted per release; a new group alerts. log |
| Escalation | The step in an alert route that sends an open, unacknowledged alert to another recipient after a set time. Alerts |
| Escape hatch | raw() on an interface: the provider's own client, logged and listed by check as outside the guarantees. Interfaces and drivers |
| Eval set | The YAML cases for one AI feature that mainsdk eval runs; CI fails when a score drops, and the result goes into the seal (planned for 0.5). ai |
| Exception | A temporary waiver of a rule in main.yaml with a rule, reason, owner and expiry; it fails again once it expires. main.yaml |
| Exfiltration guard | The in-process check on outbound calls and responses that stops secrets, labelled data and card numbers going where main.yaml doesn't declare, and holds responses over an action's bulk limit (planned for 0.4). Security model |
| Fail static | When MainSDK Cloud or delivery is down, the app keeps its last good policy, packs and config and keeps serving. Fail static |
| Fan-out | How a new feed item reaches followers: its reference is written to each follower's timeline by a job, or, for authors above fanout.threshold, merged in at read time (planned for 0.4). feeds |
| Feed | The feeds interface for follows, blocks, mutes, timelines and trending; chronological by default, with an end and a pause instead of endless scroll (planned for 0.4). feeds |
| FileRef | The record files returns for an upload: id, driver, owner, size, type and a status of pending or ready. Pass it to files.url() to get a short-lived link. files |
| Fingerprint (error) | The 16-hex hash of an error's code or name and its first three frames in your code, the same across line moves, machines and restarts. log |
| Five-minute test | The end-to-end 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, run on every change (planned for 0.3). The words we use |
| Fix | The one sentence in an error or a finding that says what to do next, starting with a verb. Errors |
| Fix-up round | In the agent benchmark, a turn after the agent says it is done in which it sees only the failing hidden tests; at most three (planned for 0.5). Agents |
| Fixture | Data a test creates with app.fixtures() in @mainsdk/testing, from the same generator as mainsdk seed, so a test can pin realistic rows (planned for 0.4). testing |
| Flag | A feature switch evaluated with flags.enabled() or flags.value(), defined in config under flags.<name>, with targeting rules and a percentage rollout by a stable hash of the user id; it changes live without a deploy. flags |
| Fleet | The enterprise plan for companies that run many MainSDK apps (planned for a later milestone). Free and Cloud |
| Fleet tenant | An enterprise in MainSDK Fleet, with a ten_… id; never shortened to tenant, which is a customer of your app. Free and Cloud |
| Forget (memory) | memory.forget(): a hard delete of a memory and every version of it, which cascades to insights derived from it, calls the driver's erase hook and returns a receipt signed by the project key; not privacy.erase(), which erases a person from every driver. memory |
| Gate | One check that must pass before a change merges, such as secrets or network. The check |
| Geo (protect) | The countries a protected asset may be opened from, with a minimum confidence, set under policy.geo (planned for 0.4). protect |
| Geo hint | A coarse place (country, region, city, time zone) read from the declared platform's headers by geo.of(req). It holds no IP address and is never an input to access: policy, access and auth.require refuse it with MAIN-GEO-0001. Location |
| Guarantee | A promise an interface keeps whatever the driver, such as an unsubscribe link on every marketing email. Interfaces and drivers |
| Guardian | The adult whom access relates to a child as guardian_of; they can pause the child's engagement messages, lower their weekly limit, widen their quiet hours and see what was sent (planned for 0.4). notify |
| Grace (licence) | The time after a licence expires, or after a revocation or suspension arrives, when licensed features stay on; it is the licence's grace claim, 0d to 90d, or the list entry's own, and its end is graceEndsAt. Licensing |
| Half-open | A TCP connection where one side has sent FIN and the other may still write; off by default, kept with halfOpen: true. net |
| Handoff | Moving an ai.run conversation to another declared agent or a person, keeping the memory scope of the person it acts for (planned for 0.4). ai |
| Happy path | The shortest correct use of an interface, at most three call lines with no config, shown first on its page (planned for 0.3). The words we use |
| High-water time | The latest time the app has seen: the clock, raised to every verified licence's iat and revocation list's issuedAt and kept in the runtime store. Licence decisions use it when the clock is behind it by more than licence.skew. Licensing |
| Hybrid logical clock | The stamp sync puts on each written field: wall time that never goes back, a counter for the same millisecond and the replica id. Stamps compare as plain text, and the later one wins a merge. sync |
| Hold | The state of an upload, media output or item that stays unreadable until the moderation pre-screen clears it; held content is never published unscreened (planned for 0.4). moderate |
| Host bus | The user-only sockets through which MainSDK apps on one machine hear each other's signals (planned for 0.4). Connected intelligence |
| Idempotency key | A key sent as the Idempotency-Key header so a provider performs a request once however often it arrives; it makes a POST retryable. network |
| Identity level | How sure an identity check is: basic, substantial or high. A market requires one under verify.require, and a driver reaches up to one. verify |
| Import source | A driver behind imports that reads rows from an outside system (rest, google-sheets, airtable), declared under imports.sources; not a connector (planned for 0.4). The words we use |
| Inbound endpoint | A path your app serves for one provider's webhooks, declared under webhooks.inbound with a preset, verified before the handler, and listed by mainsdk discover and the seal (planned for 0.3). webhooks |
| 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 (planned for 0.2). Security model |
| Incident control | A kill switch, read-only mode or sign-out cut-off, pushed as main.incident.* with mainsdk incident; it only tightens and is cleared by deleting it. Incident controls |
| Index (search) | A declared set of documents under search.indexes, mirrored from a db model through the outbox, with one copy per region; every query on it is filtered by tenant and access inside the engine (planned for 0.4). search |
| Instance | One running copy of your app: a process, container or serverless instance. Instances never talk to each other directly; they share a store, and instance.id is random per start. jobs |
| Interface | One standard contract for a capability, such as auth, db or pay; your code calls it, never the provider. Interfaces and drivers |
| Invite link | A link from links.invite() that lets a signed-in person join a list, circle or document, with uses, an expiry and an optional bound email. Organisation invites are auth.invites (planned for 0.4). links |
| Issue (schema) | One place where a value fails a schema, as { path, code, message } with no part of the value; issues travel in the problem's errors member. Not a finding. Errors |
| Issuing CA | The key that signs app licences and their revocation lists, certified by a pinned root; it rolls over without an app release. Licensing |
| Journal | Where a workflow keeps each step's result, attempt and time, so a resumed run skips finished steps; on the db driver it lives in the tenant's region (planned for 0.3). workflows |
| Journey | A durable workflow, written with journey() and usually ladder(), that reaches one person over days and ends when they come back or the guardrails stop it. engagement |
| Key package | The public keys a member's device publishes to the relay so others can add that member to an end-to-end encrypted group; the private keys stay on the device. End-to-end encryption |
| Kill switch | The incident control that refuses an action, route, interface, driver or app agent on every instance in seconds. Incident controls |
| Language SDK | One native MainSDK library per language: TypeScript first (the reference), then Rust, Python and Go in phase 5, each idiomatic, with its own releases, docs and skill and no code shared with the others (planned for 1.5). Core and language SDKs |
| Launch report | The report that shows an app meets the baseline, or exactly what remains. Adopt an existing app |
| Layer | Where a config value comes from: main.org.yaml, main.workspace.yaml, main.yaml, overlays; a layer can tighten, never weaken. main.yaml |
| Legal hold | privacy.hold(user, { until, reason }): erasure and retention stop for one person until the date, and privacy.erase refuses with MAIN-PRIV-0003. Privacy and data rights |
| Licence (app) | A vendor's signed permission for an install or a tenant to use an app's features, verified offline against a pinned root; licence.require("sso") checks it. Licensing |
| Licence (TAPS) | Permission from a TAPS Node to open one version of a protected asset, short-lived and renewed, so a revocation stops an open session within seconds (planned for 0.4). protect |
| Licensed feature | A feature name under licence.features, on only while the app licence in scope is valid or in grace and lists it. Licensing |
| Limit | A ceiling on spend or calls for a user, a feature or the app, set under limits (for example ai.limits.per-user: $1/day), or for a tenant by its plan under plans.<name>.limits; at the limit a call fails before it is made. Not a cap. AI calls |
| Listen entry | An entry under network.listen, such as tcp:7000 or tcp:9000-9010@0.0.0.0, that lets the app accept TCP connections or bind UDP on a port; loopback unless it names a bind address. net |
| Liveness and readiness | /healthz answers while the process can respond; /readyz answers 200 only when the app has started, isn't draining and its critical dependencies are up, from cached results that never block (planned for 0.4). Health and status |
| Local driver | The local driver every interface has, which needs no account, key or network; mainsdk dev and the testing kit use it, and a production check refuses it (planned for 0.3). Interfaces and drivers |
| Local mode | Running on a local driver for every interface, with no account, through mainsdk dev. CLI |
| Locked flow | A key user flow, such as sign-in or checkout, recorded before changes so every pull request must keep it working. Adopt an existing app |
| Machine fix | The patch a finding carries, a code diff or a main.yaml edit, that mainsdk fix applies; a fix that widens a grant needs a person (planned for 0.4). Repair loop |
| Machine id | m_ and 32 hex digits, a hash of the product and the machine's /etc/machine-id (machine: os) or MAINSDK_MACHINE_ID (machine: env). A licence can bind to it; licence.machine() and mainsdk licence show --machine print it. Licensing |
| The interface that receives email through your provider's inbound webhook (never an SMTP server), keeps mailboxes and threads, and pulls existing mailboxes over IMAP or JMAP (planned for 1.2). mail | |
| Main 27 | The current baseline generation: the rules every app passes and the contract versions it includes. Main 27 |
| Main mark | The label on a release that meets the baseline, such as "Pinecart 2.4.1 · Main 27" or 2.4.1+main27, backed by a signed record. Main 27 |
| 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. Declare what your app uses |
| MCP | The Model Context Protocol; MainSDK ships an MCP server for your coding agent and exposes marked actions as tools. Actions and MCP |
| MCP client | The part of your app that calls an outside MCP server, limited to the servers and tools you list in mcp.servers. Actions and MCP |
| Member | A person in a tenant, with roles in that tenant only; the same person can be an admin in one tenant and a viewer in another (planned for 0.3). auth |
| Memory | The interface that lets app agents remember the people they serve (facts, preferences, events, procedures, notes, insights), inside one tenant and one app, labelled personal and sealed with the person's key; never a driver name (planned for 0.4). Agent memory |
| Meter | The interface that records what each tenant uses, idempotently and without slowing a request, and exports closed hours to pay for usage billing (planned for 0.3). meter |
| Metric | A counter, gauge or histogram declared under analytics.metrics and exported over OpenTelemetry; never a cost (planned for 0.3). analytics |
| Minimum version | updates.min-version: the lowest client version the server serves, refused below it with 426 MAIN-UPDATE-0001; a push through config may only raise it. updates |
| Mode | How a policy acts: observe (log only, the default for new policies), warn or enforce. Policy |
| Neighbour | Another MainSDK app on the same machine that joined the host bus; declared peers may also ask it for status, a raised posture or shed load (planned for 0.4). Connected intelligence |
| Net | The interface for raw TCP and UDP: net.connect, net.listen and net.udp, checked against the protocols, ports and directions in network. net |
| Network zone | An opaque id such as z-7f3a for office or VPN addresses a protected asset may be opened from; the addresses stay in the tenant's encrypted zone table (planned for 0.4). protect |
| Norm | What normal looks like for one metric, such as requests per minute on Mondays at 10:00, learned by the app with no model (learned in the app, see norms). Connected intelligence |
| Observer | A read-only function given to observe() that receives events from diagnostics channels in a bounded queue; it can't change a decision, and a throw or a slow observer never touches a request (planned for 0.3). Not observe mode. log |
| On-store-down | The mode a limits policy declares for when its store is down or slow: open allows, closed refuses with 503, local counts on this instance only (planned for 0.3). limits |
| OpenAPI document | The OpenAPI 3.1 description of your app's public routes, written by mainsdk api openapi from your actions' schemas and served at /.well-known/openapi.json when you opt in (planned for 0.3). action |
| Operate surface | The MCP tools a running app gives agents to inspect it and ask for a playbook run that a person approves, through mainsdk ops mcp (planned for 0.4). Connected intelligence |
| Organisation | A tenant that people join, with members, roles, teams, invites, verified domains and SSO; kind: "org" in code (planned for 0.3). auth |
| Outbox | The table where tx.jobs.run(), tx.events.publish() and tx.webhooks.emit() are written in the same transaction as the data, then relayed after commit, so work happens only if the write does (planned for 0.3). db |
| Overlap window | How long the previous value of a rotated secret still verifies, so cookies and tokens signed before the rotation keep working; secrets.rotation.overlap, 24 hours by default (planned for 0.3). secrets |
| Overlay | A small file with only what differs by market, segment, environment, target or locale, such as main.in.yaml. main.yaml |
| Owner scope | Every query is tied to the user who owns the data: db.orders.for(user). db |
| Parity vectors | Golden test cases as JSON, exported from the TypeScript SDK, that another language SDK may adopt to show the same results and codes; optional data, never a gate on API shape (planned for 0.4). Core and language SDKs |
| Parser | A function from mainsdk/parse that turns raw text into a checked value, such as parse.number or parse.regex; parse.first tries parsers in order, exact, then pattern, then a model. schema |
| Peer app | Another MainSDK app this one names under apps.peers; both must name each other before either can call the other. Not an instance. main.yaml keys |
| Permissions | The main.yaml section that declares what a server-side app uses on its own machine: folders, system facts and programs. Declare what your app uses |
| Personal tenant | A tenant of one person, made at first sign-in when tenancy.personal is on, so a B2C app uses the same API as a B2B one (planned for 0.3). Data and regions |
| Pin (tool descriptions) | A hash of the tool descriptions you accepted from an outside MCP server; if a description changes, calls stop until a person accepts it. Actions and MCP |
| Pinned root | A root public key written under licence.roots (1 to 4, ed25519:) that the app trusts to certify issuing CAs. A licence verifies only through a chain that ends at one. Licensing |
| Placement | Where policy decisions run: server (default), edge or browser. Policy |
| Placement (share) | A kept getqr.id link and QR code for one place a campaign runs, such as a poster, a counter or a print insert, with first-party scan counts read only with consent; the only share that doesn't expire (planned for 0.3). share |
| Plan | One of your app's offers to its customers, declared under plans in main.yaml with its features and limits; a tenant's plan follows its pay subscription or is set by hand. MainSDK's own Free, Teams and Fleet are MainSDK plans. entitlements |
| Playbook | A rule in main.yaml that runs declared, tighten-only, expiring steps when a signal arrives, with dry-run, approval and rollback (planned for 0.4). Connected intelligence |
| Policy | Rules as code in policies/, Cedar by default or Rego through OPA, that decide sensitive calls. Policy |
| Policy bundle | A signed, versioned document of device settings rolled out in stages to a tenant or group of connected devices (planned for 1.4). Connected devices |
| Posture | The app's defence level, from normal to lockdown, raised by a playbook and lowered by expiry or a person (planned for 0.4). Connected intelligence |
| Preflight | mainsdk deploy preflight: the platform build step that fails when a required env var name is missing, a region is wrong or check --env fails (planned for 0.4). Deploy on Vercel |
| Preset | A named starting choice for mainsdk init, such as indie, that writes a minimal main.yaml; it only picks keys, and you can widen or tighten any of them. Thirty-minute path |
| 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, caches trim and health reports degraded (planned for 0.4). Health and status |
| Preview environment | A database branch for one git branch (a Neon or Supabase branch, or a local copy), migrated and seeded when mainsdk preview up makes it and deleted with the branch (planned for 0.4). testing |
| Primary (cluster) | The process cluster.run forks instances from; it serves no requests, respawns crashed instances and rolls restarts one at a time (planned for 0.4). workers |
| Problem details | The RFC 9457 error body every MainSDK error uses, plus code, fix and retryable. Errors |
| Product event | Something a person did in the app, declared under analytics.events with a consent purpose and typed props and recorded with analytics.track(); not a message on events (planned for 0.3). analytics |
| Project ID | The UUIDv7 in main.yaml, shown as prj_…; it names the project and never works as a credential. main.yaml keys |
| Prompt part | An image, PDF, audio clip or video sent to a model inside a prompt, read through files with the caller's rights and checked against limits (planned for 0.4). ai |
| Protected asset | A file put under TAPS with protect(): ciphertext that opens only with a licence (planned for 0.4). protect |
| Protection environment | The TAPS sealing service that splits and time-locks keys for release-time and threshold assets; not the seal (planned for 0.4). protect |
| Public route | The versioned HTTP route of an action, such as POST /api/v1/orders/{orderId}/refund, listed in the OpenAPI document and the typed client (planned for 0.3). action |
| Pull | One incremental read from an import source, from the tenant's cursor, on a schedule or with imports.pull(); not mainsdk sync (planned for 0.4). The words we use |
| Push (config) | A config value changed in the store while the app runs; it reaches every instance through the config driver, and a pushed main.yaml value may only tighten. config |
| Quarantine (memory) | The state of a memory written from a tool, MCP, the web or an import: returned only in the session that wrote it until a person confirms it (planned for 0.4). Agent memory |
| Query fingerprint | A query's text with every value replaced by ?, hashed to 16 hex characters; slow and repeated queries are logged by it, never with their values (planned for 0.3). db |
| Quiet hours | The time window, in a person's own time zone, in which a non-urgent notification is held until the window ends; an urgent one goes at once; alerts use it too. Notifications |
| Quota | A ceiling on how much one key may use in a window, checked with limits.quota(); a ceiling from the tenant's plan is a plan limit instead (planned for 0.3). limits |
| Reaction overlay | The expiring, tighten-only layer a playbook writes over your config; when it ends, your declared values are back (planned for 0.4). Connected intelligence |
| Read-only mode | The incident control that refuses writes in db, files, jobs and unsafe requests while reads, sign-in and the audit log go on. Incident controls |
| Readiness | See liveness and readiness. Health and status |
| Realtime | The interface for live updates from your server to browsers and phones over channels, sent as Server-Sent Events and fanned out between instances through broadcast; Pusher, Ably and Supabase Realtime come later as drivers. Formerly called broadcast. realtime |
| Recall | Reading memories back with memory.recall(), or for a model with memory.context(), which puts pinned memories first in one escaped <memory> data block; recalled text is always untrusted (planned for 0.4). memory |
| Recipe | A task-level change, such as stripe-subscriptions, applied with mainsdk add recipe across code, main.yaml, tests and docs (planned for 0.4). mainsdk CLI |
| Recipient | A named group of destinations for alerts under alerts.recipients, each a driver such as email, Slack, PagerDuty, Opsgenie or a webhook. Alerts |
| Region | Where data is stored: us, eu or in; each record goes to its owner's region. Data and regions |
| Release channel | stable or beta under updates.channels: the release offered to a user, by a stable hash of the user id, a percent of users and a percent per market. updates |
| Release time | The releaseAt instant before which no licence is issued for a protected asset, for anyone (planned for 0.4). protect |
| Rendition | One output of a video or audio at one size or bitrate, such as the 720p HLS stream; media never makes one larger than the source (planned for 0.4). media |
| Repair | A second request to a model after its reply does not match the schema. It sends the original request and the issue paths and codes, never the bad reply. repairs sets how many, from 0 to 2; the default is 1. ai |
| Report (moderation) | A person's flag on content or an account with a reason from moderate.reasons, rate-limited per person; reports on one target collapse into one case (planned for 0.4). moderate |
| Retention rule | A duration under privacy.retention for one data label, logs or analytics; privacy.retain() deletes rows and log records past it, and a label in use with no rule fails the check (MAIN-PRIV-0001). Privacy and data rights |
| Revocation list (licence) | A signed, numbered list of revoked or suspended app licences or issuing CAs; an unreachable one never blocks a valid licence. Licensing |
| Route | A declared fallback chain of models under ai.routes, called as route:<name>; a fallback never goes to a model that weakens data use or region (planned for 0.4). ai |
| Route (alert) | One entry of alerts.routes: the first whose match fits picks the recipients and any escalation. Alerts |
| Row version | The integer version of a record on a model with versions: true; update and delete take ifVersion, and the generated API sends it as ETag (planned for 0.3). db |
| Run (agent) | One agent loop from ai.run(): model turns and tool steps through actions, ended by an answer, a handoff, a wait for approval or a stop at its steps, budget or time (planned for 0.4). ai |
| Run (workflow) | One execution of a workflow, with a runId, a state such as sleeping or stuck, the current step and a history; it always resumes on the version it started on. Never called an instance. workflows |
| Replica | A device's local copy of a person's rows, kept by sync in a small key-value store. It takes writes with no network and merges them to the server on flush. sync |
| Runtime adapter | The per-runtime code inside MainSDK (Node, Bun, Deno, workerd, or a portable fallback), picked by package export conditions; the only place node:* is used. Not a framework adapter. Spec portable-core, planned for 0.4 |
| Runtime store | The one store the SDK keeps its own shared state in (limits, meter, idempotency, caches, leases), set under runtime.store (planned for 0.3). main.yaml keys |
| Sandbox | The interface that runs untrusted or AI-written code outside the app's process with limits, no secrets and only allowed hosts (planned for 0.4). sandbox |
| Sanitize | mainsdk/sanitize: turning HTML or Markdown from users or models into safe HTML from an allowlist, the same in the server and the browser; model output gets no images by default (planned for 0.2). Security model |
| Schema | A description of app data built with s from mainsdk/schema, which gives a type, a strict check and a JSON Schema; any Standard Schema value works in the same places. Not the schema: 1 key at the top of main.yaml, which is the file's format version. schema |
| Scope (API key) | An access permission an API key may use, such as orders.read; a key never widens what the policy allows. apikeys |
| Seal | The signed record of one build, served at /.well-known/mainsdk.json and checked by the app at boot; mainsdk info <url> verifies it. mainsdk CLI |
| Sealed message | The ciphertext e2e.encrypt returns, bound to its group, epoch and sender, as an object or as a string that starts e2e1.; the server stores it and can't read it, so search, moderation and analytics skip it. End-to-end encryption |
| Security event | One OCSF record, tagged with MITRE ATT&CK, about a decision the SDK made (a refused sign-in, a blocked call, a canary touch), sent to your own SIEM through the log pipeline, the OTLP exporter or events. Security events |
| security.txt | The file at /.well-known/security.txt (RFC 9116) that tells researchers how to report a vulnerability, served from inbound.security-txt (planned for 0.2). Security model |
| Seed | Synthetic demo data mainsdk seed builds per tenant from the app's schemas: the same rows for the same seed number, in the app's regions, never real personal data (planned for 0.4). testing |
| Shadow mode | Running a new driver alongside the current one and recording what it would do before you switch. Swap a driver |
| Share | A getqr.id link and QR code made with share(): private, expiring, read-only, with no personal data in the URL. Every link an app hands out is one (ADR-0056). share |
| Share driver | The driver behind share, links and every link the SDK mints: getqr, or local, which mints links on the dev server with no account and is refused in production (planned for 0.3). share |
| Shared context | Settings and progress that apps of one owner on one machine share about a person, only for a purpose that person agreed to (planned for 0.4). Connected intelligence |
| Shed | Answering a new request that isn't critical with 503 and Retry-After while the instance is past a resources.shed threshold; off until you set it (planned for 0.4). Health and status |
| Sign-in link | A link from links.signIn() sent by email or WhatsApp that signs a person in through the link method of auth, single use and expiring in 15 minutes (planned for 0.4). links |
| Signal | A typed, signed, short-lived notice such as attack.suspected or pressure.high that the app, its other instances and its neighbours hear (planned for 0.4). Connected intelligence |
| Sim | A test harness, createSim in @mainsdk/testing, that plays attacks, load curves and outages against one app or several on a fake clock and one seed, and returns a timeline that is the same every run. Testing |
| SLO | A reliability target under slo in main.yaml, such as availability: 99.9% and latency_p95: 300ms, measured from your app's own requests (planned for 0.4). Health and status |
| Snapshot | The exact text a CLI command prints for a test project, compared on every change so output stays calm and stable (planned for 0.3). CLI |
| Socket | A two-way WebSocket connection to realtime, authorised before it opens, carrying channel events, client messages and binary streams (planned for 0.4). realtime |
| 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 host, IP or range covers HTTP, HTTPS and WebSocket only. net |
| Stability | The level an interface ships at: experimental, beta or stable. Interfaces and drivers |
| Staged rollout | A broadcast reached in steps such as 1%, 10% and 100%, each judged by its bounces, complaints, unsubscribes and errors; it pauses before the next step when a threshold is crossed. Notifications |
| Standard Schema | The open interface (Standard Schema v1) that Zod, Valibot and ArkType implement. MainSDK accepts any Standard Schema value wherever it takes a schema. schema |
| Statement of reasons | What the author receives for every moderation decision: the action, facts, ground, whether automated means were used and how to appeal, exportable in the DSA Transparency Database format (planned for 0.4). moderate |
| Step | One journaled unit of a workflow, step(name, fn); once its result is journaled it never runs again, and an interrupted step reruns with the same idempotency key (planned for 0.3). workflows |
| Step-up | A person's approval before an app agent uses a risky scope of a connection, such as sending mail; one approval covers one call (planned for 0.3). Agents |
| Step-up (sign-in) | A second sign-in method that a risky sign-in must pass before its session is issued: a new device without a passkey, a new country or impossible travel. Not the step-up of a connection (planned for 0.3). auth |
| Storage driver | The driver behind files that holds uploaded files; getqr is the default, s3, uploadthing and vercel-blob are the others, and every upload is owner-scoped. files |
| Suppression list | The addresses email will not send to: a bounce or complaint blocks all email, an unsubscribe blocks marketing only. It is keyed by a hash of the address, so it holds no addresses. Email |
| System | The interface for facts about the server (user, hostname, platform, network interfaces) and the programs the app runs, declared under permissions. system |
| TAPS | Trust Anchor Provenance System, HubXero Labs' open protocol for files that carry their own identity, provenance and policy; behind protect (planned for 0.4). TAPS Node and SoveDocs |
| TAPS ledger | The tamper-evident record of TAPS registrations, rules and opens, kept alongside the MainSDK decision log (planned for 0.4). protect |
| TAPS Node | The server that checks a protected asset's policy and issues licences; the local driver fakes one in process (planned for 0.4). TAPS Node and SoveDocs |
| TCP connection | One TCP stream from net.connect or accepted by net.listen, read and written as Web streams with backpressure; a connect may be retried, an open connection never is. net |
| TCP server | What net.listen returns: a listener on one declared port that runs your handler for each TCP connection, inside a fresh context with no tenant until you set one. net |
| Team | A named group of members inside one organisation, usable as a subject in access.relate(); not the Teams plan (planned for 0.3). auth |
| Teams | The plan for people who build together, priced per active developer with a yearly maximum. Free and Cloud |
| Template | A runnable starter app, mainsdk init --template saas, agent or social, that passes its checks on local drivers; not a preset (planned for 0.5). Quickstart |
| Temporary folder | A private folder from disk.temp(), removed when the function settles and swept after a crash; needs permissions.disk.temp (planned for 0.3). disk |
| Tenant | One customer of your app whose data is kept apart from every other, an organisation or a personal tenant, pinned to one region; code reads it with tenant.current() and the SDK adds it to every query, key, file path and log record (planned for 0.3). Data and regions |
| Threshold release | A protected asset that opens only when t of its n named parties release their key shares (planned for 0.4). protect |
| Tick | The signed request a serverless platform's cron sends to /_mainsdk/jobs/tick to run one declared schedule once per slot (planned for 0.4). jobs |
| Timeline | One person's list of feed items, read with feeds.timeline(); it holds item references, so edits and removals show at once, and it ends with a caught-up or pause entry (planned for 0.4). feeds |
| Translation draft | An AI-written message held as pending until a person approves it with i18n.drafts.approve() (planned for 0.4). i18n |
| Trash | Where delete puts a record of a model with db.models.<model>.trash: hidden from reads, restorable until the period ends, then purged, and never kept past its label's retention (planned for 0.3). db |
| Trending | Windowed top-k counts of keys such as tags per region, counting distinct people with a salt that rotates each window; small counts are hidden and no person is stored (planned for 0.4). feeds |
| Trust bundle | A file under licence.trust, or the body of a refresh answer, that carries issuing CA certificates and revocation lists; each part is verified on its own like a licence file. Licensing |
| Tombstone | The stamped record sync keeps when a row is deleted, so the delete travels to every device and an older edit cannot bring the row back. sync |
| TUF | The Update Framework, which MainSDK uses to deliver signed packs and driver metadata, safe against rollback and freeze attacks. Supply chain |
| Typed client | The one TypeScript file mainsdk api client writes for your public routes: no dependency, typed inputs and outputs, problem errors, idempotency keys and page helpers (planned for 0.3). action |
| UDP socket | A bound UDP endpoint from net.udp() that sends and receives datagrams; no retries, no delivery promise, and replies only from declared peers. net |
| Upgrade notes | The file each MainSDK release ships that mainsdk upgrade reads: breaking changes with codemods, manual steps and main.yaml moves (planned for 0.5). mainsdk CLI |
| Upload | A file sent to the store behind files. The browser sends it straight to the store with a signed, single-use target from files.uploadUrl(); files.complete() then scans it and makes it readable. files |
| Verification code | The six-digit code verify.phone() sends: kept only as a keyed digest, valid for 10 minutes and 5 tries, checked once with verify.phone.check(). verify |
| Voice owner | The person whose voice a cloned voice copies; only they can consent to the clone, and withdrawing consent deletes it (planned for 0.4). ai |
| Voice session | One realtime voice conversation from ai.voice.session(), with turn detection and barge-in, on a socket, a phone call or a room (milestone 0.6). ai |
| Web Reader | The zero-install TAPS reader a protected share link opens through getqr.id (planned for 0.4). protect |
| Worker module | A file whose default export is worker(fn), run on a worker pool with workers.run and declared under workers.modules (planned for 0.4). workers |
| Worker pool | The threads, or processes with isolation: process, that run one set of worker modules; it starts empty, grows to its size and replaces a stuck or crashed member (planned for 0.4). workers |
| Worker task | One workers.run call, with its own timeout and signal; it carries the caller's tenant and trace, never its secrets. Not a job or a workflow step (planned for 0.4). workers |
| Worker thread | A thread in a worker pool. Not a job worker or a workflow worker, which claim queued work on the main thread (planned for 0.4). workers |
| Workflow | A multi-step flow written as one async function with workflow(), using step, sleep, waitFor and approve; it resumes after a crash or deploy without redoing finished steps (planned for 0.3). workflows |
| Workspace | A monorepo with one main.workspace.yaml at its root and one main.yaml per app (milestone 0.7). Monorepos |
Next
Was this page helpful?