uses

uses

Declare dependencies on other machines. Each uses statement names a single machine (by registry path or local path) that this machine depends on. The declared machines become available for ask ... from calls, tool references, and function imports.

uses replaces the legacy imports > import syntax. It is flatter (no nesting, no redundant verb) and reads naturally as English: “this machine uses the HTTP GET action.”

When to use

Use uses when your machine:

• Calls other machines via ask ... from
• References tools in ask ... using steps
• Imports function definitions from other machines (Level C, planned)
• Depends on effect machines for I/O (HTTP, database, file, etc.)

Omit uses for machines that are entirely self-contained (pure compute, no external calls). The compiler infers some dependencies from ask ... from targets, but explicit uses declarations improve clarity and enable ahead-of-time dependency resolution.

Syntax

uses "<machine_path>"

Multiple dependencies are declared with multiple uses statements, one per line:

uses "@mashin/actions/http/get"
uses "@mashin/actions/http/post"
uses "@mashin/actions/db/query"
uses "@myorg/shared/utils"

Machine path formats

Format	Example	Description
@mashin/actions/*	"@mashin/actions/http/get"	Official standard library effect machines
@orgname/*	"@myorg/effects/crm_sync"	Organization-namespaced machines from the registry
@system/*	"@system/kodada/validate"	Internal system machines
Relative path	"./shared/helpers"	Local machine in the same project

Examples

HTTP-calling machine

machine weather_checker
  uses "@mashin/actions/http/get"

  accepts
    city as text, is required

  responds with
    temperature as number
    conditions as text

  implements
    ask weather, from: "@mashin/actions/http/get"
      url: "https://api.weather.com/v1/current?city=" + input.city
      headers: {"Accept": "application/json"}

    compute result
      {
        temperature: steps.weather.body.temp,
        conditions: steps.weather.body.conditions
      }

Multiple dependencies

machine order_processor
  uses "@mashin/actions/http/post"
  uses "@mashin/actions/db/query"
  uses "@mashin/actions/db/write"
  uses "@myorg/notifications/send_email"

  accepts
    order_id as text, is required

  implements
    ask order, from: "@mashin/actions/db/query"
      query: "SELECT * FROM orders WHERE id = $1"
      params: [input.order_id]

    ask notify, from: "@myorg/notifications/send_email"
      to: steps.order.customer_email
      subject: "Order confirmed"
      body: "Your order " + input.order_id + " has been confirmed."

With selective imports (planned)

Level C function imports will allow importing specific definitions from another machine:

uses "@myorg/shared/formatters" { currency, percentage }

This syntax is accepted by the parser but the function import resolution is not yet implemented.

Migration from imports

The mashin fmt formatter automatically converts the legacy imports syntax:

// Before (legacy)
imports
  import "@mashin/actions/http" { get, post }
  import "@mashin/actions/db" { query }

// After (canonical)
uses "@mashin/actions/http/get"
uses "@mashin/actions/http/post"
uses "@mashin/actions/db/query"

Canonical ordering

uses appears early, after has and before achieves:

machine name
  has ...
  uses ...            <-- here (section 1)
  achieves ...
  accepts ...
  responds with ...

Governance

uses declarations are informational at compile time. They do not grant permissions. A machine that uses "@mashin/actions/http/get" still needs allowed to http in its ensures > permissions section to actually make HTTP requests at runtime. The uses declaration enables the compiler to resolve the dependency; the ensures section authorizes the capability.

Translations

Language	Keyword
English	uses
Spanish	usa
French	utilise
German	benutzt
Japanese	使う
Chinese	使用
Korean	사용

See also

• imports - Legacy syntax (replaced by uses)
• ask … from - Calling machines declared in uses
• defines - Machine-level functions (Level B)
• ensures - Permission declarations (separate from dependency declarations)