1. Scope and boundaries

This document defines what synt does: the process that, in front of a user request or a pattern emerging in the mnestome, grows and matures the pool of executors in Metnos. It is not a single loop: it is a cascade of strategies ordered by increasing cost, which honours the «cultivate the tools» telos without wasting frontier-LLM calls and without polluting the library.

Boundaries

The doc covers:

• the synthesis cascade in its five strategies (two reactive, three introspective);
• the R score that weighs quality, cost and originality of a proposal;
• the relationship between synt and the human gate (always present, never bypassable);
• the Python contract and the states of a synthesis request.

It does not cover, and defers elsewhere:

• the technical pipeline of generation (signing, sandbox, birth tests): see executor.html ch. 7;
• the structure of the mnestome and proto-mnests: see mnest.html and mnestome.html;
• the approval UX (batching, revocation, tutor mode): see approval_ux.html (to be rewritten);
• LLM cost tiering (local vs frontier, spending caps): see policy.html (to be rewritten).

2. What synt is

synt is the process (not an agent, not an object) with a single task: to bring into existence what the pool cannot yet do. It does not write from scratch every time, it does not write only from scratch, and sometimes it does not write at all. Its intelligence lies in knowing when to apply which strategy.

Triggers

synt comes into action in two distinct ways:

The two modes share the same cascade of strategies but differ in timing (synchronous vs asynchronous) and in tone (answer vs propose).

3. The cascade: overview

The five strategies at a glance

4. Reactive strategies: compose, generate

4.1 Compose

The basic strategy. When a proto-mnest signals an operational gap, synt first looks at the signed pool. The question is: does there exist a chain A → B → C that, executed in sequence, covers the need? If yes, synt does not write new code: it proposes the orchestration.

How the chain is searched

The mnestome is a directed graph between executors. Finding a chain that connects the requested input to the desired output is a guided walk on the graph. Three criteria order the candidates:

• Length: shorter chains are preferred.
• Average mnest weight: chains made of already-verified handoffs weigh more than speculative chains.
• Sandbox-profile coherence: a chain that touches different traces of the workspace is suspicious and must be motivated; one that stays inside a single trace (see Architecture ch. 10) is more reliable.

What a successful composition leaves behind

When synt resolves via composition, it records in the mnestome a proto-mnest pointing at the composition itself: a virtual node that says «I have just used A→B→C as if it were a single executor named X». If this proto-mnest recurs, it becomes a candidate for generalisation (ch. 5): a single executor that incorporates the chain. Composition is therefore a generalisation gym: every repeated chain is a hint for the future.

4.2 Generate

When composing is not enough — because there is no chain, because it is too long, because a missing link is critical — synt enters the multistage five-stage pipeline described in §4.2.3.

Generating costs: typically 1–2 calls at the wise tier plus human approval time. The fact that it comes after compose is not aesthetic: it is real saving.

4.2.1 Real measurements on the POC

End-to-end synthesis via wise tier = local Qwen 3.6 35B-A3B (Q4_K_M on llama-server). Case: format_json (formats a JSON string with readable indentation).

Wall-clock total of LLM stages: ~64s for the first non-trivial executor. This is time the dialog manager surfaces to the user as "I am building a new component to extend my capabilities": once signed, every subsequent reuse is pure code execution (~ms).

4.2.2 Provider-specific prompt repertoire

Each model family has idiosyncrasies that show up only with use. Synt keeps a repertoire of prompt addenda automatically applied to stages 2/3 when the caller signals for_code=True. Three style rules, ratified after the first real comparisons:

• Short: one or two lines, never a paragraph.
• Prescriptive: imperative ("Constraints: X. Y. Z."), no long-form examples, no rationale.
• The why lives in project memories, NOT in the prompt.

The repertoire lives in runtime/prompts.toml (bundled default) and is overridable via ~/.config/metnos/prompts.toml (user override). TOML schema:

[[hint]]
provider = "anthropic"
model_pattern = "claude-*" # glob on prov.model
use_case = "code_gen"
text = "\\n\\nVincoli: codice fedele alla spec. Regex semplice. Niente lookbehind/lookahead."

[[hint]]
provider = "llamacpp"
model_pattern = "qwen*"
use_case = "code_gen"
text = "\\n\\nVincoli: raw string r'...' con UN backslash. Niente triple-quote docstring."

[[hint]]
provider = "openai"
model_pattern = "gpt-*"
use_case = "code_gen"
text = "\\n\\nVincoli: compila python_code per intero (def invoke + def main). Mai vuoto."

The first match on (provider, model_pattern, use_case) wins. When a new model arrives (Gemma 5, Claude Opus 4.7, GPT-5, …) a new entry is added based on what is observed in the first syntheses. The base system prompt and the executors do not change: the only lever touched is the repertoire.

4.2.3 Multistage pipeline

The architectural answer is multistage: five small stages, each with a prompt focused on its own task, ordered from the most procedural (closed-vocabulary lookup) to the most creative (code). The manifest skeleton is filled in progressively, and each stage sees ONLY the slice it needs — no cumulative blob.

The closed vocabulary appears ONLY in the stage 1 prompt; subsequent stages receive the already-decided name and work within their own boundaries. The manifest description is not written by the developer but by the dedicated stage 4 LLM, in a four-chapter format: SCOPO: (what it does), PATTERN: (canonical call form), NON: (anti-patterns and disambiguation), OUT: (output shape). The proposer truncates the description to the head (up to OUT:) to save context budget.

Measured results on the 35-query stress dataset: stage 1 (naming + classification) reaches 88.6 % (31/35) under the bilingual prompt. The remaining 4 escalations (resize, query SQL, validate YAML, crack) are explicit rejections for verbs semantically outside the closed vocabulary, not synthesis errors: the vocabulary is only worth extending if those patterns recur in real cases («synonyms before vocabulary»).

5. Introspective strategies: merge, generalise, specialise

Introspective strategies do not answer a one-off request: they answer the structural need to keep the pool small, coherent and reusable. They run at night as part of the ager's homeostasis (see Architecture ch. 10), with low CPU and economical LLMs (local-fast tier).

5.1 Merge

When two executors have overlapping traces (weight of the mnests connecting them > threshold) and compatible sandbox profiles, synt proposes a merge: a new executor that covers both. The fused state in the executor lifecycle (ch. 6) is foreseen for exactly this case: the two originals stay loaded as long as residual mnests cite them, then they get archived.

Typical trigger: two executors that do similar things under different names (archive_pdf and store_pdf), perhaps born at different times without synt having correlated them at birth.

5.2 Generalise

When N specialised executors share the same shape (same I/O schema except for one dimension, same sandbox profile except for one parameter), and when the proto-mnests point at their family on new dimensions, synt proposes a parametric executor. The new version takes as an explicit argument what was re-encoded N times before.

Canonical example: order_image_file, order_audio_file, order_doc_file — all sort files by date — get proposed as order_file with argument file_kind. Once the generalised version is signed, the three specialised executors move to superseded and progressively to archived.

5.3 Specialise

The reverse strategy, and the rarest. From a general executor, when its invocation on a specific case recurs with very high frequency and has a costly profile or latency, synt proposes a specialised version. The specialisation lives next to the general one, not replacing it: routing becomes «if argument X ≡ hot case, use the specialised; otherwise the general one».

It applies only with measured benefit: observed latency reduction, cost reduction, or simplification of the sandbox profile. We do not specialise for preemptive optimisation.

5.4 Comparison

6. Weighting: the extended R score

Every synthesis proposal — any strategy — produces a score R ∈ [0, 1] that synt computes on observed data and that Roberto sees in the approval dossier. The formula includes a strategy_cost component that rewards the cheaper strategies:

R = 0.35 · det_pass_rate # fraction of deterministic tests passing
 + 0.20 · judge_score # LLM-as-judge (local-fast) on constitutional rubric
 + 0.15 · cost_ratio # clip(1 - actual_cost / estimate, 0, 1)
 − 0.10 · similarity_penalty # cosine-sim of embedding vs existing pool > 0.85
 + 0.10 · coverage_bonus # bonus if it covers uncovered proto-mnests
 + 0.10 · strategy_cost_bonus # 1 for compose, 0.6 for merge/specialise,
 # 0.4 for generalise, 0 for generate

gate_threshold = 0.65 # v1 DECISION

The strategy_cost_bonus is the new piece: it pushes synt towards cheaper strategies at parity of quality. A composition that closes a proto-mnest with a score similar to a generation wins because of the strategy bonus, as it should.

7. The non-retreat telos

The cascade is not just cost discipline: it is the mechanism that honours the «cultivate the tools» telos (Architecture ch. 11): as long as a user request is within the constitution and within the budget, synt exhausts the available strategies before answering «I cannot».

The telos lives in TELOS.md in the workspace, alongside the others:

5. Cultivate the tools: if I ask for something your pool cannot yet do,
 exhaust the synthesis strategies (compose, generate, ask) before
 answering "I cannot". Failure is allowed; silent retreat is not.

The difference between failure and retreat is exactly here. synt may conclude that the request cannot be satisfied within the budget, but it must do so after attempting the cascade, and it must explain it: «I tried to compose with these N executors, I tried to generate with this specification, the birth test failed on case X». A motivated failure is data for the future; a silent retreat is a hole in the mnestome.

8. Human approval, budget, abandonment

8.1 Human gate: always, everywhere

Regardless of strategy, every synt proposal that produces or modifies an executor passes through the human gate (see approval_ux.html, to be rewritten). The principle is the third of the six principles of the Architecture: no synthesis without a human filter, in any autonomy level.

A composition proposal is a separate case: synt does not create any new signed artefact, only orchestrates the execution. The human gate in this case applies to the first use (Roberto sees «I am about to call A → B → C, OK?») and is then relaxed symmetrically with the autonomy level: in Supervised every chain invocation asks for confirmation; in Full, after the first 5 clean executions, confirmation is skipped.

8.2 Budget

8.3 States of a synthesis request

9. Python contract

from typing import Protocol, Literal
from dataclasses import dataclass

Strategy = Literal[
 "compose", "generate",
 "merge", "generalise", "specialise",
]

ProposalState = Literal[
 "composing", "composed",
 "generating", "born", "abandoned",
 "proposed", "rejected",
 "fused", "generalised", "specialised",
]

@dataclass(frozen=True)
class SynthRequest:
 """A synthesis request, reactive or introspective."""
 request_id: str
 mode: Literal["reactive", "introspective"]
 proto_mnest: str | None # id of the triggering proto-mnest (reactive)
 target_intent: str # NL: what needs to be done
 budget_cents: int # frontier cap to spend
 capability_hint: list[str] # capabilities already assumed

@dataclass(frozen=True)
class RewardBreakdown:
 det_pass_rate: float # [0,1]
 judge_score: float # [0,1]
 judge_reasoning: str
 cost_ratio: float # [0,1]
 similarity_penalty: float # [0,1] (negative sign in the formula)
 coverage_bonus: float # [0,1]
 strategy_cost_bonus: float # [0,1] depends on Strategy
 total: float # aggregated R

@dataclass
class SynthProposal:
 """A concrete proposal that synt presents to the user."""
 request_id: str
 strategy: Strategy
 state: ProposalState
 artefact: dict # chain (compose) or candidate executor (generate/…)
 reward: RewardBreakdown
 cost_cents: int # consumption so far
 rationale: str # 2-3 lines NL: why this strategy, here

class Synt(Protocol):
 async def react(self, req: SynthRequest) -> SynthProposal:
 """Reactive cascade: compose first, then generate, then abandon."""...

 async def homeostasis(self, lookback_days: int = 30) -> list[SynthProposal]:
 """Sweeps mnestome and pool; returns 0..N introspective proposals in batch."""...

 async def revise(
 self, request_id: str, feedback: str,
 target_strategy: Strategy | None = None,
 ) -> SynthProposal:
 """Resumes a proposal after human feedback."""...

# Errors (logged and turned into state, not propagated)
class StrategyExhaustedError(Exception):...
class BudgetExceededError(Exception):...
class PolicyVetoError(Exception):...
class ConstitutionViolationError(Exception):...

10. Audit and observability

Every step of the cascade produces a JSONL line in workspace/.audit/synt/YYYY-MM-DD.jsonl. Example for a successful composition:

{
 "ts": "2026-04-25T22:14:33Z",
 "request_id": "01HX...",
 "mode": "reactive",
 "proto_mnest": "mnest_01HW...",
 "strategy": "compose",
 "state": "composed",
 "chain": ["read_files", "read_files_pdf", "classify_entries", "move_files"],
 "reward": {"total": 0.78, "det_pass_rate": 0.95, "…": "…"},
 "cost_cents": 0,
 "duration_ms": 142
}

Three invariants of the synt audit, guaranteed by loader and runtime:

1. Complete traceability: for every request_id the entire sequence of states visited is on record, up to a terminal state.
2. Motivated decisions: every transition between strategies includes a NL rationale readable by Roberto after the fact.
3. Cost recorded: the sum of cost_cents for a request never exceeds the declared budget_cents; the final line certifies it.

11. Alternatives considered

12. Conformance tests

13. Open questions

1. Home of the three introspective steps. Stay in synt.html, or migrate to a new consolidator.html? The split could simplify the contracts (synt = reactive, consolidator = introspective) but would duplicate parts of the weighting. For now: all here. Open.
2. Homeostasis timing. Fixed nightly or load-adaptive? For Metnos on metnos-server with a single user, nightly suffices; for multi-sender scenarios it should be revisited. Open.
3. Reinforced compositions → promotion. How many recurrences of the same chain trigger a generalisation proposal? Tentative default: 5 in 30 days. To be calibrated.
4. Graph walk for compose. Algorithm: breadth-first over the mnestome with pruning by minimum weight? A* with I/O coverage heuristic? Open — for now plain BFS.
5. Signature revocation. When Roberto rejects an already born proposal after n invocations, is it an archive or a quarantine? The executor lifecycle (ch. 6) admits both; criterion not yet fixed.
6. Remote synt. In topologies with remote executors (Architecture ch. 4), does the cascade run on the metnos-server server or can it spawn compositions that span server and laptop? Open; conservative default: all on metnos-server, remote executors called like any other.

Metnos — synt, canonical microdesign.