Capability field reference
Developer/Operator reference. These tables describe the authoring fields shipped with the deployed Java service. Use Console validation for the final acceptance of a draft.
Shared value model
An atom names a declared predicate and its named arguments:
{"predicate":"order","args":{"id":"?order_id","status":"pending"}}A string beginning with ? is a variable. The same variable means the same value within a rule or Action. Bind a variable in a positive premise before using it in a conclusion. A negated or absence premise cannot supply missing values.
Keep business keys explicit. Cases share the Agent's graph; a Case selection does not implicitly scope every predicate.
Portable capability
A Capability contains Vocabulary, Rules, Actions and Sources, and can declare Case Contracts. Its immutable Release identifies the content installed on an Agent. Connections, local paths, credentials and independent Constitution clauses are not portable capability content.
Vocabulary, Rules and Actions
| Field | Requirement | Type | Meaning |
|---|---|---|---|
id | required | identifier | Stable package name; starts with a lowercase letter. |
title | required | non-empty string | Human-readable package title used in Console and the capability library. |
summary | optional | string | Short catalog summary; presentation metadata, not executable semantics. |
judges | optional | string[] | Catalog and discovery tags; presentation metadata, not executable semantics. |
vocabulary.defines[].id | required | namespaced predicate id | Canonical semantic identity such as acme.finance.invoice_approved. Definitions in one Domain Program use one namespace. |
vocabulary.defines[].as | optional | local identifier | Package-local alias. The final id segment is used when omitted. |
vocabulary.defines[].args | required | string[] | Ordered argument names; their order is the canonical word signature. |
vocabulary.imports[].id | optional | canonical predicate id | A shared predicate this program may read. Imports are explicit and read-only. |
vocabulary.imports[].as | optional | local identifier | Unique package-local alias used by Rules and Actions. |
rules[].id | required | identifier | Stable rule id, unique within the board. |
rules[].label | required | string | Human explanation shown as the basis of a conclusion. |
rules[].when | required | Atom[] | Non-empty premises. Variables must be bound by a positive premise. |
rules[].then | required | Atom[] | Non-empty conclusions. Built-ins and naf are not allowed here. |
acceptance[] | optional | AcceptanceBridge[] | Completion bridges. The body binds an acceptance node and positive evidence; the single conclusion is acceptance_met for that node. |
actions[].action | required | identifier | A board-state transition name; distinct from an external Tool. |
actions[].description | optional | string | Human explanation of the transition. |
actions[].preconditions | required | Atom[] | Facts that bind parameters and must hold before the transition; use an empty array for an unconditional transition. |
actions[].effects | required | Atom[] | Facts consumed or produced after success. It may be empty only when execution is present and the Action exists solely to obtain a trusted receipt or returned facts. |
actions[].execution | optional | Execution | Makes the Action externally executed. It references one versioned Tool and one Source; Adapter details are forbidden here. |
actions[].execution.tool | conditional | versioned Tool id | Stable Tool contract such as acme.invoice.read@1. Required when execution is present. |
actions[].execution.source | conditional | source name | The one governed Source bound to this Action. Multiple candidate Sources require distinct Action names; Source is never an ApplyAction argument. |
actions[].execution.kind | conditional | read | write | run | External effect class. It does not choose the local Adapter. |
actions[].execution.params | optional | Record<name, string | number | boolean (+ ? for optional)> | Typed argument contract. Values supplied to ApplyAction are bindings, never facts. |
actions[].execution.inputPolicy | optional | grounded | clue | read defaults to clue; write and run default to grounded. Grounded parameters bind from positive trusted preconditions; clues only seed acquisition. |
actions[].execution.humanOnly | optional | boolean = false | If true, only human clearance can release the exact Action instance. |
actions[].execution.returns | optional | ReturnMapping[] | Maps trusted structured receipt columns to attested board facts. |
Use canonical predicate names or declared imports. Reference installed definitions rather than copying them into model assertions. Use Action preconditions and declared inputs to state what evidence must support execution.
For an Action that runs a Worker Tool, the declared Tool and the configured Worker must agree. A field appearing in a draft does not itself grant a runtime permission.
Built-in operators
The following operator descriptions come from the deployed authoring manifest. They describe the accepted authoring interface, not the language used to implement the current server.
| 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. |
Test arithmetic boundaries, zero divisors, missing values and failed comparisons. The JSON interface still constrains representable values; do not rely on a language-specific conversion to repair an invalid value.
Sources
| 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. |
sources[].name | required | string <= 64 | Logical Source name referenced by executed Actions and Worker Tools. |
sources[].type | required | db | file | http | mcp | sensor | compute | human | Worker access family. It determines connection, access, and territory semantics. |
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. |
Sources declare logical evidence requirements. Bind their physical locations and Connections in the Agent's Runtime configuration. Source trust and material-delivery permission are separate controls.
Worker Tool Manifest
| 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. |
A Tool manifest selects an Adapter, a fixed operation and bounded execution settings. Secrets belong in the Worker vault or operator environment.
Use the runtime's supported Adapter and manifest format, and check that the Worker reports the required Tool. Do not infer tool availability from a capability's declaration alone.
Agent and Worker setup explains the ordinary workbench path. The published runtime contains the implementation and advanced integration reference.
Constitution
| 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. |
Constitutions are separate from capability business rules and local Tool configuration. Review the effective policy on the Agent. Editing a draft does not modify an installed immutable Release.
Snapshot and validation
Java 6b1ddc3 / Rulith 0.8.17
These tables are extracted from pinned release artifacts. A later development schema is not automatically available on the hosted service. Validate the complete draft in Console, publish it separately, and check effective installation before running it.