Home / Learn / 12 Capabilities

Release v0.4.0Edition 0.2

12.9 Recap and reference

Page 10 of 10

12.9.1 For agents

una --json check . reports the capability diagnostics of this chapter, the U3xxx codes, in the domain authority. For forgetting to hand over a binding:

json
{"schema":"una.diagnostics/1","diagnostics":[{"schema":"una.diagnostic/1","code":"U3001","severity":"error","domain":"authority","message":"`dispatch` needs `@log: Console[print]`, which is not in scope here","primary":{"file":"src/notices.una","start":{"line":106,"col":3},"end":{"line":106,"col":20}},"related":[],"repairs":[{"rank":1,"escape_cost":0,"widens":{"kind":"authority","cost":"the function then holds this authority, and every caller must hold it too: check that the operation belongs to this function's job"},"description":"declare `uses @log: Console[print]` in the header","edit":{"file":"src/notices.una","start":{"line":102,"col":32},"end":{"line":102,"col":32},"replacement":"\n  uses @log: Console[print]"}}],"explain":"una explain U3001"}],"fixable":0}

A repair that gives a function more authority carries widens, with its kind (authority, or grant for U3012) and its cost, and ranks after the repairs that keep authority. una fix skips the repairs that widen:

Terminal
$ una fix --dry-run .
skipped src/notices.una:102:32 U3001 declare `uses @log: Console[print]` in the header: widens authority

The compact rule: every effect is @binding.op(...) on a binding of the header's uses; bindings pass by name or through with; a handler implements every operation of its capability and keeps its contract; main gets only the granted host capabilities.

12.9.2 Recap

  • A function's uses list everything it may do outside the program; a pub function without uses is pure.
  • List the operations a function needs; a callee holds only those its header lists.
  • Bindings pass by name, or through with for one statement; a capability is never a value.
  • Host capabilities reach main only as [run] grants and --grant allow; grant the least that works.
  • Declare each outside service as a capability, with a handler for each way to provide it; every handler implements every operation.
  • A clause such as if error use on an operation's call keeps a function working when a service fails.
  • A function argument with effects needs uses of and fails of (edition 0.2).
  • Edition 0.3 adds conditions on operations (section 13.1), ceilings for modules (section 13.2), narrowed rebindings with @x = @y[ops] (Granting less at the call) and locked contracts (section 13.3).

12.9.3 Reference

Next:13 Limits on authority