Governance

mashin programs produce intents, not effects. Every step that reaches the outside world first produces an intent, and the runtime mediates that intent before anything happens. Governance is a structural consequence of this design: because programs never act directly, the runtime can check every intent against the machine’s declared rules.

The ensures section declares what a machine can and cannot do. The runtime enforces it. There is no way to bypass it because the capability to bypass it does not exist in the language.

The ensures section

Every machine that performs governed operations needs an ensures section:

machine research_agent

  ensures
    permissions
      allowed to
        model
        network.http
        memory
      not allowed to
        database.write
        shell
      requires approval for
        network.http.post

This machine can reason (LLM calls), make HTTP requests, and use semantic memory. It cannot write to a database or run shell commands. External API calls require a human to approve each one at runtime.

Three permission levels

allowed to

Grant capabilities. The machine can perform these operations without interruption:

permissions
  allowed to
    model, network.http

not allowed to

Explicitly deny capabilities. If a step tries to use a denied capability, the runtime halts execution and records the denial in the behavioral ledger:

permissions
  not allowed to
    database.write, filesystem

requires approval for

Capabilities that need human consent at runtime. The execution pauses, presents the request to the user, and continues only if approved:

permissions
  requires approval for
    network.http.post

Capabilities

Each step type needs specific capabilities:

Step	Required capability
ask ... using	model
ask ... from / action ... call	call (or the target machine’s specific capability)
action ... http	network.http
remember / recall	memory
action ... exec	shell
action ... db	database.read or database.write
compute / decide	None (pure, always allowed)

Guards

Guards validate data before and after steps. Each guard has a name and an action to take when violated:

ensures
  permissions
    allowed to
      model
  guards
    pii_detection
      on_violation: "redact"
    content_safety
      on_violation: "block"
    max_tokens: 4096

Action	What happens
"block"	Halt execution, return an error
"redact"	Remove the violating content and continue
"warn"	Log a warning and continue
"retry"	Re-run the step with guardrail feedback

Needs

Declare external requirements that must be present before the machine runs:

ensures
  needs
    api_key: required
    database_url: required

If a declared requirement is missing at runtime, the machine fails immediately with a clear error. No steps execute.

A complete example

machine customer_support_agent
  accepts
    message as text, is required
    customer_id as text, is required
  responds with
    reply as text
    escalated as boolean
  behaves
    recall find_history
      query: input.message
      collection: "support_history"
      namespace: input.customer_id
      limit: 3
    ask respond, using: "anthropic:claude-sonnet-4-6"
      with role "You are a customer support agent. Be helpful and professional."
      with task "Customer message: ${input.message}\n\nPrevious interactions:\n${steps.find_history.results.map(r => r.content).join(\"\\n\")}"
      returns
        reply as text
        escalated as boolean
    remember save_interaction
      content: input.message + "\n" + steps.respond.reply
      collection: "support_history"
      namespace: input.customer_id
  ensures
    permissions
      allowed to
        model
        memory
      not allowed to
        database.write
        shell
      requires approval for
        network.http.post
    guards
      pii_detection
        on_violation: "redact"
    needs
      api_key: "required"
  verifies
    test "responds using support history"
      assuming find_history {results: [{content: "Asked about billing last week."}]}
      assuming respond {reply: "I can help with that.", escalated: false}
      assuming save_interaction {ok: true}
      given {message: "My invoice looks wrong", customer_id: "cus_1"}
      expect {reply: "I can help with that.", escalated: false}

This machine can reason and use memory, but cannot write to a database or run shell commands. PII in model responses is automatically redacted. It requires an API key to start.

What gets recorded

Every governance decision is recorded in the behavioral ledger:

• Which capability was requested
• Whether it was allowed, denied, or required approval
• The rule that matched
• The inputs to the decision
• A hash proving the record was not tampered with

This is how mashin delivers auditability. You can always answer the question: “Why did this machine do that?”

Try it

Take the sentiment classifier from Your First Ask Step and add governance. Declare model permission. Then add not allowed to filesystem and a PII detection guard. Run the machine and check the behavioral ledger to see the governance decisions recorded.

Next steps

• Permissions and the Blast Radius - How far a machine can reach, who decides it, and what the record says
• Inputs and Outputs - Validation constraints as the first line of defense
• Actions - How governed actions work with stdlib machines
• ensures reference - Full specification