Key Concepts

Intent-Driven Computing

Coding is writing at the level where the computer thinks. mashin is writing at the level where you think.

The word “coding” means encoding: translating your intent into the machine’s language. mashin closes that gap. You describe what the system should do in mashinTalk, a declarative language that reads like a plan, not code. The platform handles the encoding.

mashinTalk isn’t natural language. It’s a small, structured vocabulary: machine, step, ask, compute, decide, call, remember. But it maps to how humans describe what intelligent systems should do. A compliance officer can read the permissions. A product manager can follow the steps. An LLM can write it.

When your machine wants to send an email, call an API, or query a database, it does not execute the action directly. It produces an intent: a structured description of what it wants to do. The runtime evaluates that intent against your governance policies, records the decision, and only then executes.

This is why governance in mashin is structural rather than bolted on. There is no way to bypass it because the language provides no mechanism for direct effect execution. Every external action passes through the same governance boundary.

The consequences are practical: every execution is replayable (the intent stream is complete), every action is auditable (every decision is recorded), and governance policies can be simulated before deployment (replay historical intents against new rules).

Machine

A machine is the fundamental unit in mashin. It has a name, accepts inputs, produces outputs, and implements behavior through steps. Every machine is a .mashin file.

machine greeter
  accepts
    name as text, is required
  responds with
    greeting as text
  implements
    compute greet
      {greeting: "Hello, " + input.name + "!"}

Steps

Steps are the actions a machine performs. Each step has a type that determines what it can do.

Step	Purpose	I/O
compute	Pure computation (math, data transformation)	None
ask ... using	Send a task to an LLM	Governed
ask ... from	Call an effect machine (HTTP, file, database)	Governed
decide	Branch based on conditions	None
remember	Store information in semantic memory	Governed
recall	Retrieve information from memory	Governed
wait for	Suspend execution until an event occurs	Governed

Steps execute in order within an implements section. Each step’s output is available to subsequent steps via steps.<name>.<field>.

Governance

Governance is what makes mashin different from every other AI framework. The ensures section declares what a machine is and is not allowed to do.

ensures
  allowed to reason
  allowed to call "@mashin/actions/http/get"
  not allowed to file_write
  requires approval for send_email

These are not suggestions. The runtime enforces them. If a machine tries to do something it is not allowed to do, the execution stops and the denial is recorded in the behavioral ledger.

Why this matters: In other frameworks, an LLM agent can call any tool, access any API, and perform any action. Governance is added as middleware or prompt instructions that the model can ignore. In mashin, governance is structural: every action begins as an intent, and the runtime decides whether to allow it. The capability to bypass governance does not exist in the language because the language does not provide direct effect execution.

Cell

A cell is your mashin environment. It contains your machines, their execution history, credentials, and settings. Every cell has the same shape whether it runs on your laptop, a Docker container, or in the cloud.

~/.mashin/cells/default/
  mashin.db          # machines, runs, ledger, vectors
  history.git/       # version control for machines
  credentials.db     # encrypted API keys and secrets

You can have multiple cells (personal, work) on one machine. The cloud runs one cell per organization. See Cells for the full guide.

Behavioral Ledger

Every machine execution produces a trace in the behavioral ledger. The trace records:

• What steps ran and in what order
• What the LLM was asked and what it returned
• What governance decisions were made (allowed, denied, approval requested)
• How many tokens were used and the estimated cost
• A hash chain proving the trace was not tampered with

The ledger is not optional. It is produced automatically by every execution. This is how mashin delivers auditability.

Koda

Koda is the intelligent development environment. It is not an assistant or chatbot. The entire interface is intelligent: you work in projects, books, and sessions, and Koda provides context-aware help throughout. Koda’s cognitive operations are themselves mashin machines, so they are governed and auditable. See Koda for the full guide.

Kura

Kura is the package registry. You publish machines as krates (versioned packages) and discover machines published by others. Every published krate goes through 6-level cryptographic verification: file integrity, artifact identity, publisher authenticity, envelope integrity, registry attestation, and lineage provenance. See Publishing & Kura for details.

Next steps

• Machine Anatomy - Deep dive into how machines are structured
• Governance - How permissions, trust levels, and approval gates work
• Platform Overview - How all the platform components fit together