1. Scope and boundaries

This document defines what an executor is, how it is built, how it is authenticated, how it is isolated, how it is born, how it dies. It is the first of three canonical docs introduced by the Dialogue on executors and distributed memory (24 April 2026), together with mnest and mnestome. It replaces the old neuron.html: technically the same object, but the name «neuron» carried a biological metaphor that became cumbersome at the implementation level. Executor is more precise: it is executable code.

Boundaries

This document covers:

• the structural contract of an executor (header, manifest, signature, profile, code);
• the state machine of its lifecycle;
• the execution flow as seen from the gateway;
• the synthesis pipeline that turns a proto-mnest into an executor.

It does not cover, and defers to other docs:

• the structure of mnests and the mnestome (see the dedicated docs);
• Vaglio policies (see vaglio.html, in Italian and pending rewrite);
• the technical isolation profile (see sandbox.html, in Italian and pending rewrite);
• the workspace (see workspace.html, in Italian and pending rewrite).

2. What an executor is

An executor is a unit of code that Metnos can run as a step of its own reasoning. A function with a public contract, a signed identity, an isolation profile, and a manifest that describes what it does and which resources it touches. Nothing more. Not an agent, not a microservice, not a plugin: a small executable block under the project's signature.

Three categories, one external anatomy

The distinction between seed and synthesised is historical, not structural: a seed is generated manually before first boot, a synthesised one is generated automatically while the system is alive. Once signed, the gateway treats them in exactly the same way.

Builtins are different: they share the external contract with seeds and synthesised (same run(args, ctx) -> dict, same audit, same I/O schema), but they do not have a separate manifest.toml, no per-instance profile.lock, no synthesis pipeline. They live in the Metnos sources and are signed as part of the release. The synt can never generate a builtin (ch. 7): they are foundational, not synthesisable.

3. Anatomy: the six artefacts

An executor lives under workspace/executors/<name>/. The directory contains six artefacts, in this reading order:

4. Identity: manifest, signature, version

The manifest

The manifest is the identity document of an executor. Example for fs_read:

[executor]
name        = "fs_read"
version     = "1.0.0"
created_at  = 2026-04-25T08:12:00Z
created_by  = "seed"               # or: "synt:<run_id>"
summary     = "Read a file from the workspace and return its content."

[contract]
input_schema  = "schema.json#/definitions/Input"
output_schema = "schema.json#/definitions/Output"
error_classes = ["NotFound", "PermissionDenied", "TooLarge"]
idempotent    = true
side_effects  = false

[sandbox]
profile = "fs-read-workspace"      # see sandbox.html
hash    = "blake3:abc123..."       # fingerprint of the profile

[audit]
trace_topic = "executor.fs_read"

Three fields are normative:

• name and version form the identity the gateway uses to resolve every invocation. name is immutable for the entire life of the executor; version follows semver with one hard rule: any change to the code or the contract bumps the major.
• contract is the usage schema. You cannot add or remove an input field without bumping the version.
• sandbox.hash ties the identity to the profile. Changing profile means changing identity.

The signature

The file manifest.sig contains the Ed25519 signature (curve 25519, private key under ~/.config/metnos/keys/ with 600 permissions, never versioned) over these concatenated bytes:

blake3(manifest.toml) || blake3(main.py) || blake3(schema.json) || profile.lock

The gateway loader, at boot and at every request, verifies:

1. the signature is valid against the project's public key;
2. the four hashes match the files on disk;
3. the manifest is semantically coherent (valid schema, existing profile).

If even one check fails, the executor is rejected. Not loaded, not invoked, not deleted: it is moved to quarantine (ch. 6) and surfaced to the user.

Versioning

A version of an executor is never modified «in place». To change something, a new version is created (e.g. 1.0.0 → 2.0.0) with its own signature. The gateway can keep multiple versions loaded in parallel as long as there are mnests citing them (see mnest.html). Promoting a new version to default is an explicit, signed act: it is recorded in workspace/executors/<name>/CURRENT.

5. Sandbox profile

The profile is the point where an executor's identity meets perimeter safety (Architecture ch. 5). The section is longer than usual because two distinctions must be pinned down, and the question «can the executor read outside the sandbox?» deserves an operational answer, not a slogan.

5.1 Declared profile vs applied sandbox

Two different things, coupled, often confused:

The two layers are kept in sync by the profile lock described in ch. 3: the hash of the concrete profile, computed at signing time, is frozen in profile.lock. At every invocation, the gateway loader recomputes the hash of the sandbox it is about to apply and compares it with the lock; on mismatch, the invocation fails. A silent profile change — by anyone — is intercepted.

5.2 The five dimensions of the profile

5.3 Can it read outside the sandbox? No, never. Why.

Short answer: no. What the profile does not grant, the executor's process does not see and cannot see. This is not a style recommendation, it is a kernel constraint.

Long answer, in three steps:

1. Mount namespace. bubblewrap opens the process in a private mount namespace where only the paths listed in the profile are visible (mounted read-only or read-write according to the field). The rest of the filesystem simply does not exist from the process's point of view. An open('/etc/passwd') returns ENOENT (file not found), as if the file had never been there.
2. Landlock. On top of the mount namespace, the kernel applies a landlock policy that further restricts: even paths mounted read-only cannot be opened for writing, even writable paths cannot be opened with dangerous flags. A violation returns EACCES.
3. Seccomp. Network syscalls are filtered by seccomp: an executor with no network in its profile receives EPERM on connect(). An executor with allow-listed network goes through a local proxy that blocks anything outside the allow-list.

This is defence in depth: the first level (mount namespace) already suffices for unlisted paths; the second (landlock) handles read/write nuances; the third (seccomp) closes the network side. Three independent kernel mechanisms, configured by the profile. Bypassing them would require a kernel bug, not an executor bug.

5.4 Operational example: fs_read called wrong

Suppose the gateway receives the request: fs_read({path: "/etc/passwd"}). The executor fs_read has profile fs-read-workspace which grants read-only on workspace/. What happens?

The correct design is that the error is intercepted at step 1 (policy-time), not at step 2 or 3 (kernel-time): it is faster, more informative for the caller, and leaves no traces in the sandbox. Steps 2 and 3 are the safety net that exists if the first should fail because of a bug of ours.

5.5 Core forbidden paths: above the profile

Some paths no profile can grant, even if the manifest declared them. They are the core forbidden paths, hard-coded in the gateway's code, irreducible, modifiable only by rite (code change, review, release):

• ~/.ssh/, ~/.gnupg/ — the user's cryptographic keys;
• ~/.config/myclaw/, ~/.config/metnos/ — the project's secrets vault;
• workspace/.audit/ — the append-only ledger of actions; not even modifiable by the audit log writer itself, which opens the file in append mode via dedicated syscall;
• system areas (/etc/, /proc/, /sys/, with explicit exceptions for innocuous files read by the Python runtime).

Conceptual difference: the profile is per-executor declared modulation; the core forbidden paths are universal system prohibitions. They live on two different planes of axis 2 of perimeter safety (Architecture ch. 5): the modulable shell (profiles) and the hard core (forbidden paths). The Full autonomy level can widen the shell, never the core.

5.6 Can I derogate? Paths outside the workspace, and the «tidy the photos» case

Yes. Nothing in the design forbids a profile from declaring paths outside workspace/. The profile is an explicit declaration: one can declare ~/Pictures/, ~/Documents/work/, a network-mounted folder, a backup partition. What the profile declares, the sandbox grants; what the core forbids stays forbidden anyway (ch. 5.5).

The derogation, however, is a weighed act. It has three constraints:

1. It is explicit. It must be declared in the manifest, not implicit. A reviewer reading the manifest must see immediately that this executor touches ~/Pictures/ and not just the workspace.
2. It is signed. A widened profile changes the profile.lock hash; changing the profile means changing the version, and changing the version requires a new signature and a new approval. The sandbox cannot be widened in secret.
3. It stays under the core. Even a profile that declares ~/ read+write cannot access ~/.ssh/, ~/.gnupg/, ~/.config/myclaw/: the core forbidden paths (ch. 5.5) are masked by the mount namespace even inside a «wide» profile.

Use case: tidy the photos

A real case. The photos live in ~/Pictures/ (on the server) or in C:\Users\Roberto\Pictures\ (on the laptop). The two situations are distinct and are solved distinctly.

6. Lifecycle: seed, active, fused, quarantined, archived

7. Synthesis (synt): from proto-mnest to executor

The synt is the process that brings new executors to life when use demands it. The trigger source is a recurring proto-mnest: a trace of unsatisfied desire («the output of A was meant to go to B which does not yet exist») that recurs several times in the same month.

The pipeline has seven stages. Each stage may suspend and ask the user.

The split is sharp: synt proposes, the user approves. No synthesis without a human filter; this is the third of the six principles (ch. 14 of the Architecture). The detail of the pipeline lives in synthesizer.html (in Italian and pending rewrite).

7.1 The cascade: compose first, generate later

The seven-stage pipeline above is the generation arm: it produces a brand-new executor. But it is not the first tool the synt reaches for when a proto-mnest recurs. The canonical sequence is a cascade:

The three introspective steps (merge, generalise, specialise) do not yet have a dedicated doc; the natural home is either an extra chapter within the future rewritten synt, or a new consolidator.html. Open decision.

8. Execution: invocation from the gateway

The flow of an invocation from the gateway to an executor goes through eight steps. Here is the high-level sequence; the detail of intermediate steps (Policy, Vaglio, sandbox) lives in their respective docs, all pending rewrite.

1. The gateway receives an action: call executor X with input {...}.
2. It resolves X via workspace/executors/X/CURRENT; if there is no CURRENT or it is quarantined, it fails.
3. It verifies signature and profile lock. If broken, quarantine and failure.
4. It validates the input against schema.json. If invalid, structured-error failure.
5. It opens the sandbox with the declared profile. The four Laws act here as an additional filter.
6. It runs run(args, ctx). Time limit, memory limit, network limit.
7. It validates the output against schema.json. If invalid, failure.
8. It writes to the audit log: who called, with what, for how long, what came back (in normalised form, with secrets redacted).

Along the flow, the gateway updates two structures:

• the turn record of the request, which becomes part of the execution trace;
• the mnestome, in particular the mnest that links the caller to this executor. See mnest.html.

9. Audit and observability

Every invocation produces a JSONL line in workspace/.audit/executors/YYYY-MM-DD.jsonl:

{
  "ts":         "2026-04-25T08:14:33.881Z",
  "trace_id":   "01HW...",
  "turn_id":    "01HX...",
  "executor":   "fs_read",
  "version":   "1.0.0",
  "caller":     {"kind": "user", "sender": "roberto", "channel": "telegram"},
  "input":      {"path": "workspace/notes/journal.md"},
  "output":     {"size": 4231, "sha":"blake3:..."},
  "duration_ms": 18,
  "exit":       "ok"
}

Three invariants the loader and the runtime guarantee:

1. append-only: the audit file is never modified; corrections are written as a subsequent rectification line.
2. self-describing: every line carries everything needed to reconstruct the invocation, without cross-referencing other sources.
3. redacted: recognised secrets (API keys, passwords, tokens) are replaced by a placeholder with their hash, never stored as plaintext.

10. Examples: three seeds and one builtin

Three seed examples

fs_read

Reads a file from the workspace. Profile: read-only filesystem on workspace/; no shell, no network; max duration 2 seconds; max output 4 MB. Errors: NotFound, PermissionDenied, TooLarge. Idempotent.

web_fetch

Fetches a web page and returns it as text or markdown. Profile: no filesystem, outbound network on HTTP/HTTPS toward an allow-list of domains (configurable per instance); max duration 15 seconds; max output 2 MB. Errors: DnsError, Timeout, Forbidden, TooLarge. Idempotent.

telegram_send

Sends a message to the user's trusted chat. Profile: no filesystem, outbound network only to api.telegram.org; max duration 5 seconds. Side effects: yes (sends a message). Errors: RateLimited, Unauthorized, Network. Not idempotent: two calls with the same input send two messages.

A builtin example: scheduler

scheduler is the first (and so far only) builtin executor proposed: it invokes another executor (or chain) at a defined cadence. It is the mechanism that makes «requests with schedule» possible without inventing a separate design category. It replaces the wrong idea of «agreed routines» as a stand-alone object.

Contract

Output: {schedule_id: ULID, next_fire: timestamp}.

Sibling operations, also builtin: scheduler.list (list active schedules), scheduler.cancel (close a schedule), scheduler.modify (change cadence, expiry, count or channel). Every modification passes through the human gate if it changes cadence or target_executor.

Profile (declared in code, not in a manifest)

• Filesystem: read/write on workspace/.runtime/scheduler.sqlite (the schedule store).
• Network: none directly; but it can invoke executors that use the network (separately authenticated).
• Special capabilities: system:scheduler (access to the gateway's async loop, never grantable to a seed or synthesised).
• Idempotent: schedule creation is (same configuration → same schedule_id, identical return). Firings are not, they depend on the target.

Audit

Every firing emits a JSONL line like any other executor invocation, with caller = {"kind": "scheduler", "schedule_id": "…"}. A schedule's history is reconstructable by schedule_id: creation, modifications, every firing, eventual closure.

scheduler is the first builtin because it solves a recurring case (mailbox monitoring, daily summary, periodic checks) with a mechanism that composes naturally with the synt cascade: a recurring schedule becomes a candidate for fusion (synt ch. 5.1) into a single executor that incorporates the chain.

11. Renaming: neuron → executor

The previous microdesign used the term neuron (neuron.html, now deprecated and marked untrusted). The Dialogue on executors and distributed memory renamed it to executor for two reasons:

1. Precision. A biological neuron is not signed executable code, has no manifest, has no sandbox profile. The metaphor helped early brainstorming but became a burden in technical docs.
2. Alignment with execution. The gateway speaks to executors: executable code invoked to produce a result. The name remembers that verb.

The biological term still works well to describe the emergent mnestome as a graph: that is a different layer of metaphor (graph as tissue), to which we return in the dedicated docs.

12. Remote executors: same contract, process elsewhere

The topology (Architecture ch. 4) states that some executors, in the future, will not run on metnos-server but on the user's machines: the laptop first of all. This chapter says what changes, in concrete terms, for the executor microdesign when the process no longer lives on the server.

What does NOT change

The contract of a remote executor is identical to that of a local one. Same anatomy (ch. 3): TOML manifest, Ed25519 signature, main.py code, I/O schema, birth tests, profile lock. Same synthesis pipeline (ch. 7). Same gateway-side identity (ch. 4). Same lifecycle (ch. 6). Same central audit log, on metnos-server (ch. 9): who calls a remote executor and what comes back is traced exactly as for a local one.

The remote executor's manifest still lives on the server metnos-server, under workspace/executors/<name>/. The server is the canonical source of the «who» and the «what». On the laptop only the execution lives: a small confined process, launched and supervised from the server side through the Headscale channel (see Architecture ch. 4).

What changes, and why

Example: photo_organize on the laptop

The canonical example from ch. 5.6: tidy a photo archive of ten thousand files that live in C:\Users\Roberto\Pictures\. Syncing them to the server, tidying them, syncing back implies gigabytes of traffic, double disk usage, time windows in which the same file exists in two states on two machines. An in-place rename performed directly by the laptop solves it in one second. But the process that performs that rename must be trusted and traced like every other Metnos executor.

The flow, in concrete terms:

1. Synthesis. The synt (ch. 7) proposes photo_organize with manifest declaring: input = list of sort rules, output = number of tidied files, profile = read-write on C:\Users\Roberto\Pictures\ (excluding reserved sub-folders), no shell, no network. Roberto approves, the manifest is signed on the server.
2. Device pairing. From Telegram, Roberto confirms that the laptop «Acme-15» may run remote executors. The ceremony generates a pairing key that lives in the mnestome and in the small runtime on the laptop.
3. Distribution. The gateway sends the signed binary of photo_organize to the laptop, which verifies it against the manifest and writes it to local cache.
4. Invocation. Roberto says «tidy the 2024 photos by capture date». The gateway prepares a call with unique trace_id, writes on metnos-server the «before» manifest (list of paths that will be renamed, hashes), then sends the call to the laptop via Headscale + mTLS.
5. Local execution. The small runtime on the laptop verifies authenticity and signature, opens the weak sandbox (AppContainer/NTFS permissions) with the declared profile, performs the rename, returns the outcome.
6. Audit. Two JSONL lines: one on metnos-server (who called, when, outcome), one on the laptop (list of paths actually touched, hashes after). Correlated by trace_id.
7. Possible undo. If Roberto changes his mind, the gateway reads the «before» manifest and sends the laptop the inverse call. Reversibility is preserved.

13. Open questions

1. Signing key. The Ed25519 key lives under ~/.config/metnos/keys/. When a new device must be allowed to sign new executors (e.g. Roberto's laptop on the road), how is it authorised? Device pairing (ch. 4 of the Architecture) plus time-bound delegation? Open.
2. Sharing across instances. If Metnos becomes multi-instance in the future (remote executors on a second device), how does the signature of a new executor propagate? Replication with verification on the remote side? Open.
3. Versions in flight. A new version of an executor under test coexists with the old one. For how long? Is promotion manual or does it have an automatic threshold? Open, see roadmap phase 4.
4. Manifest validation. Will we use a TOML parser that exposes positional errors? Is there a compatibility test with the toolchain? Open.

Metnos — executor microdesign v1.1 — 2026-04-24
New canonical doc. Replaces neuron.html (deprecated).