Iii Core PrimitivesSAFE

Effortlessly compose, extend, and observe every service in real-time for the first time ever.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: iii-core-primitives
description: >-
  Use when registering iii functions, binding triggers, observing functions, selecting
  sync/void/enqueue invocation, creating workers, inspecting the live worker registry, installing
  registry workers, authoring event sources, moving channel data, or adapting external HTTP
  functions across TypeScript, Python, and Rust.
---

# Core Primitives

iii has three top-level primitives:

- **Function**: a named unit of work such as `orders::validate`
- **Trigger**: an event source bound to a function
- **Worker**: a process that connects to the engine and executes functions

Since 0.25 every function is also **observable**: `iii.observe(source, target)` invokes `target`
on each invocation of `source` that passes its filters. Observers replace trigger bindings over
time; the built-in providers (`http`, `cron`, queue, `state`, `stream`, pub/sub, database) still
use trigger types in 0.25, so keep `registerTrigger` for them. See `iii-observe`.

Use `::` in function IDs, leading slashes in HTTP `api_path`, and `expression` for cron config.

## Function Registration

Register local handlers when you control the implementation. Register HTTP-invoked functions when
iii should call an existing external endpoint.

| Shape | Use for |
| --- | --- |
| `registerFunction(id, handler, options?)` | Local worker code |
| `registerFunction(id, HttpInvocationConfig, options?)` | Existing HTTP services |
| `registerTrigger({ type, function_id, config, metadata? })` | Binding a built-in event source (deprecated in 0.25, still required for providers that have not migrated) |
| `observe({ function_id, args?, filters? }, target, options?)` | Running `target` after another function's invocations, or on an engine event (`iii-observe`) |
| `trigger({ function_id, payload, action?, timeout? })` | Calling any function by ID |

Functions and triggers can carry metadata for ownership, discovery, and generated skills. Do not put
secrets in metadata.

## Workers and Registry

A worker is any process that connects to the engine and registers functions or trigger types. There
are two common paths:

| Task | Use |
| --- | --- |
| Create your own worker | Write SDK code that calls `registerWorker`, `registerFunction`, and `registerTrigger` or `observe` |
| Add an existing capability | Browse `https://workers.iii.dev/`, then call `compose::add worker=<name>` |
| Pin a worker version | `compose::add worker=<name>@<version>` |
| Declare a local worker | Add `worker: path://./workers/my-worker` under `containers:` |
| Reproduce a project | Commit the exact versions in `worker-compose.yaml` |

The public worker registry at `workers.iii.dev` is for installable workers such as HTTP, state,
queue, pub/sub, cron, database, shell, console, rbac-proxy, and other capability workers.
(`iii-sandbox` and `iii-observability` are engine-owned and are not added through the registry.) Those workers may ship their own function-level skills; do not duplicate every capability
as a top-level iii skill.

### Worker Manifest

Use `iii.worker.yaml` when iii should start a local worker project:

```yaml
name: math-worker
runtime:
  kind: python
  package_manager: pip
  entry: math_worker.py
scripts:
  install: "pip install -r requirements.txt"
  start: "python math_worker.py"
```

The manifest describes how to start the process. Once running, the WebSocket connection and function
registrations are what make the worker part of iii.

### Live Engine Registry

The engine keeps a live registry of connected workers, registered functions, triggers, and trigger
types. Read it through the built-in discovery functions:

| Function | Returns |
| --- | --- |
| `engine::workers::list` | Connected workers and metrics |
| `engine::functions::list` | Registered functions |
| `engine::triggers::list` | Registered triggers |
| `engine::trigger-types::list` | Advertised trigger types and schemas |
| `engine::observers::list` | Observers you may see (`function_id`, `namespace`, `worker` filters) |

For topology changes, observe the engine-hosted sources `engine::on-workers-changed` or
`engine::on-functions-changed` with `deliver: 'input'` (see `iii-observe`). The older
`engine::workers-available` and `engine::functions-available` trigger types still fire.

## Built-In Trigger Shapes

The workers behind these types have not moved to source functions in 0.25, so bind them with
`registerTrigger`. Each call logs a one-time deprecation warning per process; it is informational
and the binding works as before. For `log`, the engine also hosts the `observability::on-log`
source (`iii-observe`).

| Trigger type | Registration config | Handler payload |
| --- | --- | --- |
| `http` | `{ api_path: "/orders/:id", http_method: "POST" }` | `{ query_params, path_params, headers, path, method, body }` |
| `cron` | `{ expression: "0 0 9 * * * *" }` | `{ trigger, job_id, scheduled_time, actual_time }` |
| `durable:subscriber` | `{ topic: "payments" }` | The queued message payload |
| `subscribe` | `{ topic: "orders.created" }` | The published event payload |
| `state` | `{ scope: "orders", key?: "order-123" }` | `{ event_type, scope, key, old_value, new_value }` |
| `stream` | `{ stream_name, group_id, item_id? }` | Stream event details |
| `log` | `{ level: "warn" }` | OpenTelemetry-style log data |

Add `condition_function_id` to built-in trigger config when the handler should only run if a boolean
condition function returns `true`. With `observe`, a condition you can state over the event becomes a
declarative filter; a condition that needs code stays on `registerTrigger` or moves into the target.

## Invocation Modes

| Mode | Shape | Use when |
| --- | --- | --- |
| Sync | `trigger({ function_id, payload })` | The caller needs the result |
| Void | `TriggerAction.Void()` | Optional side effect, no result needed |
| Enqueue | `TriggerAction.Enqueue({ queue })` | Reliable async work with queue policy |

Use enqueue for work that must complete 

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

sdk/packages/node/iii/local.yml

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Iii Core Primitives](https://modelsatlas.com/skills/iii-hq/iii-core-primitives/badge.svg)](https://modelsatlas.com/skills/iii-hq/iii-core-primitives/)

Not your listing, or something out of date? Claim or update your listing.