← Documentation index Architecture guide › changes

Metnos

Change lifecycle

One shared object for proposing, deciding, applying, and observing a change.

Sources that suggest an improvement do not modify Metnos directly. They translate the suggestion into a change_intent: a typed record with origin, target, rationale, score, and state. The /admin/changes page presents these records and keeps their progress visible.

The shared object
States and transitions
Active sources
Materialization, application, and observation
What gets applied
Natural-language example
Guarantees and limits

1. The shared object

Records are stored in ~/.local/state/metnos/change_intents.sqlite. Their main fields are:

Group	Contents
Identity	An `id` and deterministic fingerprint for deduplicating equivalent proposals.
Provenance	Source family, module, original identifier, and discovery time.
Intent	Closed kind, target, summary, rationale, and kind-specific payload.
Priority	Score, confidence, and number of converging sources.
Decision	Person, action, reason, and decision time.
Outcome	Applied effect, observed metrics, error, or rollback data.

The fingerprint excludes the source family. If two sources describe the same change, the upsert can merge them into one record and increase convergence without duplicating the action. A score is an ordering aid, not an authorization.

2. States and transitions

proposed  --accept--> accepted --apply--> applied
    |                       |                  |
    |                       +--error--> failed +--measure--> observed
    +--stage--> staged                              |
    +--reject--> rejected                           +--ok--> finalized
                                                   +--problem--> rolled_back

A staged proposal may return for review. A failed change may be retried or rejected. Rollback is terminal in the registry and performs a physical reversal when the change kind supports one. The state machine blocks arbitrary jumps: a proposal cannot become applied before it is accepted.

3. Active sources

The materializer reads four side-effect-free adapters:

Source	What it can produce
Telos	Executor creation or extension and a controlled pipeline trial, from actionable cluster heads.
Introvertiva	Executor deduplication; it also preserves already-recorded states that must remain inspectable.
Synt	Executor-creation requests and their terminal or in-progress states.
User feedback	A proposal to reject a pattern after at least two consistent negative reports.

Adapters translate different storage formats into the same schema. They neither apply the change nor turn an automatic inference into human consent.

4. Materialization, application, and observation

Task	Default frequency	Responsibility
`change_intent_materialize`	Daily at 01:00	Reads adapters, deduplicates by fingerprint, and updates the store.
`change_applier`	Every 10 minutes	Processes up to 20 accepted records and records either their effect or error.
`change_observer`	Daily at 03:15	Measures up to 200 applied or observed changes and decides whether to finalize or roll them back.

The default observation period is seven days and can be changed with METNOS_CHANGE_GRACE_DAYS. Criteria vary by kind: executor health, alias integrity, the result of the turn used to try a pipeline, or new feedback about a rejected pattern.

5. What gets applied

Kind	Current effect	Rollback
`create_executor`	Starts executor synthesis; an existing executor is not duplicated.	Archives the synthesized executor.
`extend_executor`	Extends the manifest, stores a copy, and signs the executor again.	Restores the stored manifest and re-signs it.
`dedupe_executors`	Creates an alias and retires the duplicate only when provenance permits it.	Removes the alias and reactivates the duplicate.
`materialize_pipeline`	Runs the proposed request once as a real turn, under normal policy and controls.	Records rollback; the turn installs no persistent pipeline artifact to remove.
`reject_pattern`	Adds the approved pattern to the registry of paths to avoid.	Removes the matching registration.
`cache_pattern`	Remains supported for compatible records already present in the store.	Demotes the associated registration.

6. Natural-language example

Ask Metnos with a request like this example: “Show me the system changes waiting for my decision and explain the first one in plain language.”

Decisions are made in the web chat. If you are talking to Metnos through Telegram, open the web chat, enter the administration area, and choose Changes; the technical route is /admin/changes. The page can filter by state, source, and kind and offers only the transitions allowed for each record.

7. Guarantees and limits

Acceptance is an explicit decision attributed to the administrator; a high score does not replace it.
The applier is idempotent per kind and writes a local audit. An error leads to failed, not apparent success.
Rollback depends on the kind. A pipeline run as a real turn cannot reverse external effects that have already occurred; normal consent gates still apply before execution.
Text produced by automatic generators helps triage, but must be read alongside provenance, payload, and recorded effects.

Code references: runtime/change_intents.py, runtime/change_intent_adapters/, runtime/jobs/change_intent_materialize.py, runtime/change_applier.py, runtime/change_observer.py, runtime/change_rollback.py, and runtime/http_routes_admin.py.