Capability field reference

This page is the authoring contract for portable Capability content, independent Constitution policy, and the local Worker Tool Manifest. The tables are generated from the same manifest used by Console validation and suggestions.

Use the visual editors in Agent → Configuration for ordinary Capability authoring. Use the JSON view when you need advanced rule or Action fields. Use Connections → Worker Tool Manifest for a quick local Tool definition. Validation is authoritative: saving a draft does not install it, installation is a separate governance operation, and downloading a local manifest does not upload it.

Shared value model

An atom has this shape:

{"predicate":"order","args":{"id":"?order_id","status":"pending"}}

predicate names a declared word or a built-in operator.
args is an object keyed by the argument names declared in vocab[].args.
A string beginning with ? is a variable. The same variable name means the same value within one rule or action.
Literal strings, finite numbers, booleans, and null are values. Integer arithmetic is exact only inside JavaScript's safe-integer range, ±(2⁵³ − 1).
naf: true is allowed only on a premise. It means the atom cannot currently be proved. It does not bind variables.
negated: true represents explicit negative evidence. It is different from naf.

A variable used in a conclusion, action effect, or computed result must first be bound by a positive premise. Built-in operators may appear in when or action preconditions, never in rule conclusions.

Capability manifest

The market-level rulith-capability/1 manifest presents four sections—Vocabulary, Rules, Actions, and Sources—while grouping one required Knowledge wire package (Vocabulary + Rules + Actions) with one optional Sources wire package. It contains identity, version, author, component package names, and content digests. It contains no Adapter configuration, credentials, Connection names, or Constitution clauses. Installation resolves the ordinary components and sends each through the normal governance path.

Knowledge

Knowledge defines the vocabulary, derivation criteria, acceptance bridges, and board-state transitions for one workflow family.

Field	Requirement	Type	Meaning

Minimal example:

{
  "id": "invoice_checks",
  "title": "Invoice checks",
  "vocab": [
    {"predicate": "invoice", "args": ["id", "subtotal", "tax"]},
    {"predicate": "invoice_total", "args": ["id", "amount"]}
  ],
  "rules": [
    {
      "id": "invoice_total_rule",
      "label": "Total equals subtotal plus tax",
      "when": [
        {"predicate": "invoice", "args": {"id": "?id", "subtotal": "?subtotal", "tax": "?tax"}},
        {"predicate": "add", "args": {"left": "?subtotal", "right": "?tax", "result": "?total"}}
      ],
      "then": [{"predicate": "invoice_total", "args": {"id": "?id", "amount": "?total"}}]
    }
  ]
}

acceptance[] uses the same {id,label,when,then} envelope as rules[], but its conclusion is deliberately restricted. Each bridge must:

include a positive acceptance premise that binds the leaf node variable;
include at least one positive evidence premise if the bridge is expected to reach a trusted completion tier (naf is not evidence);
conclude exactly one acceptance_met atom for that same node variable.

These bridges tell the host both how completion is proved and which evidence work must be requested. Do not move them into ordinary rules.

actions[] is the single Agent-facing operation model. Every Action has {action, description?, preconditions, effects}. preconditions binds its instance from supported board state; effects records the board transition after success. A local Action has no execution. An outward Action adds execution with one versioned Tool, one Source, and an effect class. Adapter, executable, query, endpoint, and credential fields are rejected from governed Action content.

Example executed Action:

{
  "action": "read_invoice",
  "description": "Read one requested invoice",
  "preconditions": [
    {"predicate": "invoice_requested", "args": {"id": "?invoice_id"}}
  ],
  "effects": [],
  "execution": {
    "tool": "acme.accounting.read_invoice@1",
    "source": "accounting",
    "kind": "read",
    "params": {"invoice_id": "?invoice_id"},
    "returns": [
      {"predicate": "invoice", "args": {"id": "$invoice_id", "subtotal": "$subtotal", "tax": "$tax"}}
    ]
  }
}

The model requests read_invoice; it does not supply an Adapter or invent free-form business parameters. The board binds ?invoice_id, and trusted receipt fields referenced with $column may enter the board only through the declared return mapping and Source scope.

Built-in operators

All operators below are available in rule premises and action preconditions. Arithmetic is exact-or-fail: unsafe integer input or output, division by zero, and non-finite results are rejected rather than rounded.

Operator	Group	Meaning
`eq(left, right)`	comparison	Equality.
`neq(left, right)`	comparison	Inequality.
`lt(left, right)`	comparison	Strictly less than.
`lte(left, right)`	comparison	Less than or equal.
`gt(left, right)`	comparison	Strictly greater than.
`gte(left, right)`	comparison	Greater than or equal.
`between(value, low, high)`	comparison	Inclusive numeric range check.
`contains(left, right)`	text	True when the left string contains the right string.
`add(left, right, result)`	arithmetic	Exact addition.
`sub(left, right, result)`	arithmetic	Exact subtraction.
`mul(left, right, result)`	arithmetic	Exact multiplication.
`div(left, right, result)`	arithmetic	Division; fails on zero or a non-finite result.
`mod(left, right, result)`	arithmetic	JavaScript-style remainder; fails on zero.
`pow(left, right, result)`	arithmetic	Exponentiation; fails on a non-finite result.
`idiv(left, right, result)`	arithmetic	Floor division; exact integer inputs only.
`imod(left, right, result)`	arithmetic	Mathematical modulus paired with floor division.
`min(left, right, result)`	arithmetic	Numeric minimum.
`max(left, right, result)`	arithmetic	Numeric maximum.
`neg(left, result)`	arithmetic	Arithmetic negation.
`abs(left, result)`	arithmetic	Absolute value.
`sign(left, result)`	arithmetic	Returns -1, 0, or 1.
`sqrt(left, result)`	arithmetic	Square root; fails outside its finite domain.
`ln(left, result)`	arithmetic	Natural logarithm; fails outside its finite domain.
`exp(left, result)`	arithmetic	Natural exponential; fails on a non-finite result.
`concat(left, right, result)`	text	String concatenation.

mod is remainder. Use idiv and imod together when you need floor-division semantics and a non-negative mathematical modulus for a positive divisor.

returns and effects become board evidence only after a trusted successful receipt. A model message, an Action declaration, or a successful network call by itself does not upgrade evidence.

Sources

Sources describe who may attest which words and provide non-secret deployment hints. A Source package is a reusable template. Installing or configuring it creates live governance records; those records, not the template card, are the operational source of truth.

Field	Requirement	Type	Meaning
`format`	fixed	`rulith-sources/1`	Source-template format identifier.
`meta.name`	required	`identifier`	Stable source-template package name.
`meta.version`	optional	`number = 1`	Template version.
`id`	compatibility	`identifier`	Legacy Console/library alias; accepted for existing drafts, while runtime identity remains meta.name.
`title`	compatibility	`string`	Legacy library title accepted for existing drafts; it does not affect accreditation.
`sources[].name`	required	`string <= 64`	Logical Source name referenced by executed Actions and Worker Tools.
`sources[].type`	optional	`db \| file \| http \| mcp \| sensor \| compute \| human`	Worker access family; form is derived for compatibility.
`sources[].form`	compatibility	`sensor \| compute`	Legacy projection derived from type; accepted for existing packages but omitted from new visual authoring.
`sources[].words`	required	`string[]`	Predicates this source is allowed to attest.
`sources[].tier`	optional	`attested \| perceived`	Suggested evidence ceiling; installation governance decides the effective tier.
`sources[].territoryHint`	optional	`string <= 240`	Human deployment or jurisdiction hint.
`Agent source instance.connection`	deployment	`Agent-owned connection name`	Not package content. After installation, governance binds each source instance to exactly one Worker Connection owned by the same Agent.
`sources[].access`	conditional	`address <= 240`	Non-secret endpoint or path required when configuring a live source.

{
  "format": "rulith-sources/1",
  "meta": {"name": "accounting_sources", "version": 1},
  "sources": [
    {
      "name": "accounting",
      "type": "mcp",
      "words": ["invoice"],
      "tier": "attested",
      "territoryHint": "Customer-controlled environment"
    }
  ]
}

Never put tokens, passwords, DSNs, private keys, Connection IDs, or credential-bearing URLs in a Source package. tier is a requested ceiling, not self-issued authority. Effective accreditation is decided when the live Source is created and bound to one Connection owned by the same Agent.

Worker Tool Manifest and Adapters

A Tool is a stable, versioned capability contract. An Adapter is a fast local recipe that implements it. The Worker Tool Manifest is deployment configuration, not a Capability component and not an Agent-visible choice.

Field	Requirement	Type	Meaning
`format`	fixed	`rulith-worker-tools/1`	Local manifest format. This file is not uploaded or published as a Capability.
`tools.<versioned-id>.adapter`	required	`http \| mcp \| db-query \| db-exec-fenced \| run \| workspace`	Local implementation recipe for the versioned Tool. Workspace is built into the reference Worker and normally enabled through environment configuration rather than a manifest row.
`tools.<versioned-id>.source`	required	`source name`	Must equal the Source referenced by the Action and be bound to the same Agent-owned Connection.
`tools.<versioned-id>.entry`	required	`string`	Adapter entry: relative path, request path, MCP Tool name, or fixed query template, depending on the Adapter.
`tools.<versioned-id>.fence`	optional	`object`	Adapter-specific bounds such as method, timeout, response size, or row limit.
`tools.<versioned-id>.handles.verification`	optional	`string[]`	Verification work kinds this Tool handles through the same Adapter path.
`tools.<versioned-id>.handles.evidence`	optional	`string[]`	Evidence material kinds this Tool handles through the same Adapter path.

{
  "format": "rulith-worker-tools/1",
  "tools": {
    "acme.accounting.read_invoice@1": {
      "adapter": "mcp",
      "source": "accounting",
      "entry": "read_invoice",
      "fence": {"timeoutMs": 30000, "maxResponseBytes": 16384}
    }
  }
}

The manifest may implement many Tools, but a Connection can dispatch only the exact Tool IDs whose ID, digest, and Source were pinned on its first authenticated poll. Every Tool Source must already be bound to that same Connection. Changing an Adapter, entry, fence, or Tool inventory changes the digest; governance must reissue the Connection before the Worker can pin the new manifest.

Adapter meanings:

http calls a relative request path under Source-resolved endpoint and credentials.
mcp calls a fixed MCP Tool name under the Source-resolved server.
db-query executes one read-only parameterized query with bounded results.
db-exec-fenced executes one fenced parameterized mutation.
run executes a relative fixed program beneath the Worker root without a shell.

The browser builder under Connections is the quickest way to produce this file. Keep secrets in the Worker vault or environment; never place them in the downloaded manifest.

Constitution

Constitution contains plain-language constraints evaluated before outward effects. It is intentionally small: workflow logic and Tool references belong in Knowledge, Source scope belongs in Sources, and physical execution belongs in the Worker Tool Manifest.

Field	Requirement	Type	Meaning
`format`	fixed	`rulith-norms/1`	Constitution format identifier.
`meta.name`	required	`identifier`	Stable Constitution package name.
`meta.version`	optional	`number = 1`	Constitution package version.
`norms[].id`	required	`identifier`	Stable clause id.
`norms[].title`	required	`string`	Short clause summary shown at clearance time.
`norms[].version`	optional	`number = 1`	Clause version.
`norms[].text`	optional	`string`	Full natural-language wording shown to the reviewer.

{
  "format": "rulith-norms/1",
  "meta": {"name": "invoice_policy", "version": 1},
  "norms": [
    {
      "id": "invoice_policy_human_payment",
      "title": "Payments above the configured threshold require human approval",
      "version": 1,
      "text": "Release only the exact payment instance approved by an authorized human reviewer."
    }
  ]
}

Installed clauses are immutable in the current profile. Tighten policy by adding a clause. Do not edit a draft and assume it changed an already installed Agent.

What the editors intentionally hide

The visual forms hide fixed format markers, generated compatibility fields, credentials, and unsupported core-only sections. Expert JSON remains available for the advanced fields listed on this page. If a field is absent from these tables, Console may reject it even if an internal or older core format once used the same name.

For runtime operations, continue with the MCP reference. For execution and receipt behavior, see Agents and Workers.

Privacy Terms Contact