AbstractRuntime 0.17.0__tar.gz → 0.18.0__tar.gz

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/CHANGELOG.md

@@ -10,6 +10,95 @@ Unreleased changes live in [`changelog.d/`](changelog.d/README.md), one file per
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-11-04
+
+### Added
+
+- **Acquaintances of an entity or a session** (`identity/acquaintances.py`, framework backlog 1119):
+  `entity_acquaintances(home_dir, run_store)` and `session_acquaintances(session_id, run_store)` answer two
+  lists, the other entities and the humans it interacted with, each with first and last seen, the number of
+  interactions and the task kinds. Computed from existing records, never stored: the participants the
+  gateway stamps on visit, summon and meet runs, the person who started a run (`_meta.origin`), and who left
+  a task in the task inbox. Identifiers only; interactions with no usable identifier (an `agent:` participant,
+  a participant without a namespace, a person-started run without an actor) are listed under `not_counted`,
+  never guessed. See `docs/track-record.md#acquaintances`.
+- **An entity's digital identity: its look and its voice, one record in its home**
+  (`abstractruntime.identity.digital_identity`, framework ADR 0052 draft, backlog 1119; `docs/digital-identity.md`).
+  `<home>/identity.json` holds the avatar design, its colour and the voice (`schema_version` 1). `write_identity` checks
+  every bound (`IdentityInvalid` names the field), runs the gateway's `check` hook, appends an `identity_changed` row to
+  `state_history.jsonl` (the `phase_changed` field names) before the file is replaced atomically, and never gives a
+  `rev` twice: one write at a time per home (`<home>/.identity.lock`, held from the read to the file replace). A
+  file it cannot read in full raises `IdentityUnreadable` on read and on write, never "no identity".
+  `default_identity` is the recorded default anyone can recompute (SHA-256 of the entity id, eight engraved Watch
+  designs, an HSL colour, the gateway's default voice as a value); `record_default_identity` writes it once and never
+  overwrites. `identity_at_rev` answers an old rev from the biography. The reference `entity:castor#3` rides
+  `vars._runtime.identity_ref` beside the signed entity stamp (`stamp_run_identity_ref`, `read_run_identity_ref`,
+  `parse_identity_ref`). `identity_fingerprint` derives the individual's `actor_id` from the manifest, with the diary's
+  chain head. Homes without `identity.json` are untouched.
+- **The summon tells the entity when its look or voice changed**: one sentence ("Your voice changed on 4 November (by
+  laurent): now fr-male-rene.") in the summon prelude, after the identity core, when the change is newer than the
+  previous summon (`render_summon_prelude(home_dir=, identity_since=)`, `ChatSession(identity_since=)`,
+  `build_visit_workflow(identity_since=)` or `_visit.identity_since` seeded by the door).
+- **The idle unload reaches the host: `set_model_idle_unload(seconds)`** (host facade, `LocalAbstractCoreLLMClient`,
+  `MultiLocalAbstractCoreLLMClient`; framework backlog 1115). It relays AbstractCore's process-wide idle-unload time
+  (ADR 0012, default 60 minutes): a model no call has used for that long is unloaded, a locked model never is, and a
+  running call is never interrupted. `None` or `0` turns it off; a refused value answers `ok: false`. Local residency
+  rows of in-process text models carry `idle_unload_s`, `last_used_at` and `idle_unload_at`, and pass through Core's
+  `in_use` and `locked_by`, so a host can show a model that is in use, or kept loaded by another account.
+- **`set_model_residency_locks(locks)`**: the locked models become exactly the listed ones (resident ones locked,
+  missing ones loaded then locked, the others unlocked), each pair with its own outcome. A lock names a provider and a
+  model; the `base_url` of a configured endpoint is not part of the key. A host stores its "Keep loaded" set and
+  replays it at start; as a `set_` name it is replayed when the gateway's model host rebuilds a client.
+- **Track record and reputation of an entity or a session** (`identity/track_record.py`, ADR 0052 §5-§6,
+  framework backlog 1119). `entity_track_record(home_dir, run_store, ledger_store, *, book_head)` and
+  `session_track_record(session_id, run_store, ledger_store)` answer sessions, runs, successes, failures,
+  cancelled, in progress and tokens (input, output, total), per task kind (`<phase or role>/<workflow_id>`,
+  from ids only) and overall; `compute_reputation(record)` gives trust per task kind,
+  `(successes + 1) / (successes + failures + 2)` with its support, the support-weighted overall, and the
+  last 20 outcomes as evidence ("no experience yet" when there is none). Everything is computed from
+  existing records; nothing is stored. Only work from outside counts: turn roots a person or a trigger
+  started and automation occurrences (once each, however many attempts); sub-runs, controllers, the
+  session memory run and runs another run or the system started never do. Outcomes come from the run
+  status, the occurrence's `automation.completed` decision, an entity task marked `done`, and the work
+  order verdicts (`done:` / `blocked:`). Feedback from people and agents (`feedback_user`,
+  `feedback_agent`) is typed but has no source yet, so every answer says `basis: "completion-rate only"`.
+  Each answer names its subject's `identity_ref` and, for an entity, its `identity_fingerprint`.
+  See `docs/track-record.md`.
+- **`metrics_many` also returns `tokens_input` and `tokens_output`** (SQLite ledger): `usage.input_tokens`
+  (else `prompt_tokens`) and `output_tokens` (else `completion_tokens`) of completed `llm_call` records.
+  Existing keys are unchanged.
+- **`identity.life.read_work_order_verdicts(home_dir)`**: the verdicts the work lane archived in
+  `work_order.done.md`, oldest first.
+
+### Changed
+
+- **AbstractCore 2.34.0 or newer** (base install, `apple` and `gpu` settings): the idle unload and its residency rows
+  come from it.
+- **A load with `ttl_s` or `keep_alive` on an in-process model** still lists them under `unsupported_options`; its
+  warning now names the idle unload that applies instead ("the idle unload setting applies (60 min unused, never while
+  it is kept loaded)"), or says it is off.
+
+### Fixed
+
+- **A run store whose index cannot attribute a session is refused, never started as a plain chat**
+  (`core/run_attribution.py`, framework backlog 0938). A third-party store with `list_run_index` but no `session_kind`
+  in its rows (an index written before automations v1) used to report "no kinds" and let a `discussion-session:` start
+  through as an ordinary chat, skipping the discussion's read-only anchor. It now raises `SessionAttributionError`
+  naming the missing column; a store with no index at all names both methods it lacks. Built-in stores are unchanged.
+  Upgrading a custom store: add `session_kind` and `role` to its index rows, or implement `session_kinds(session_id)`
+  (see `docs/automations.md`, "Storage guarantees").
+- **A tool that reports its failure as a JSON object keeps its explanation** (`integrations/abstractcore/tool_executor.py`,
+  framework backlog 1005). A failed result's `output` used to be emptied when the tool returned its failure as a JSON
+  string, so the agent and the run ledger saw only the error line (for a web search: "No results found", never the
+  backends tried, the bot-challenge status or the hint). The parsed object is now the result's `output`, as for a tool
+  that returns a dict; a plain text error (`Error: ...`) still keeps an empty output and its message in `error`.
+- **The visual-flow Agent node shows the model that explanation** (`visualflow_compiler/compiler.py`). A failed call
+  whose `output` is an object is rendered as its error line followed by the object (`[web_search]: Error: No results
+  found` then the JSON), under the same `agent_observation_max_chars` limit; a plain text failure still shows its error
+  line alone.
+- Failure payloads are now recorded in the run ledger and the history bundle like success payloads: whatever a tool puts
+  in its failure JSON (its parameters included) is stored with the run.
+
 ## [0.17.0] - 2026-11-03
 
 ### Added

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: AbstractRuntime
-Version: 0.17.0
+Version: 0.18.0
 Summary: AbstractRuntime: a durable graph runner designed to pair with AbstractCore.
 Project-URL: AbstractCore (website), https://www.abstractcore.ai/
 Project-URL: AbstractRuntime (GitHub), https://github.com/lpalbou/abstractruntime
@@ -20,7 +20,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
-Requires-Dist: abstractcore>=2.33.0
+Requires-Dist: abstractcore>=2.34.0
 Requires-Dist: abstractmemory>=0.4.0
 Requires-Dist: abstractsemantics>=0.0.5
 Requires-Dist: anyio<5.0.0,>=4.12.1
@@ -35,14 +35,14 @@ Requires-Dist: reportlab<5.0.0,>=4.0.0
 Requires-Dist: restrictedpython>=7.0
 Requires-Dist: unstructured[docx,odt,pptx,rtf,xlsx]<0.19.0,>=0.18.32
 Provides-Extra: apple
-Requires-Dist: abstractcore[apple]>=2.33.0; extra == 'apple'
+Requires-Dist: abstractcore[apple]>=2.34.0; extra == 'apple'
 Requires-Dist: setuptools<82.0.0,>=80.10.2; extra == 'apple'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
 Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
 Provides-Extra: gpu
-Requires-Dist: abstractcore[gpu]>=2.33.0; extra == 'gpu'
+Requires-Dist: abstractcore[gpu]>=2.34.0; extra == 'gpu'
 Requires-Dist: setuptools<82.0.0,>=77.0.3; extra == 'gpu'
 Provides-Extra: test
 Requires-Dist: aiosmtpd<2.0.0,>=1.4.4; extra == 'test'
@@ -55,10 +55,32 @@ Description-Content-Type: text/markdown
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.17.0 • **Python:** 3.10+
+**Version:** 0.18.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.18.0
+
+- **Models unload after being idle**: a host sets how long a local model may sit unused (`set_model_idle_unload`,
+  AbstractCore's default 60 minutes; off with `None` or `0`); a running call is never interrupted and a model kept
+  loaded never unloads. `set_model_residency_locks` relays the host's "Keep loaded" set, and both come back after a
+  model-host restart. Loaded-model rows say when a model was last used, whether it is in use, who keeps it loaded
+  and when it unloads. Requires AbstractCore 2.34.0 or newer.
+- **A failed tool keeps its explanation**: a tool that reports its failure as a JSON object (a web search's backends,
+  bot-challenge status and hint) keeps it in the result, the run ledger and what the visual-flow Agent node shows
+  the model, after the error line.
+- **A store that cannot attribute a session is refused**: a custom run store whose index rows lack `session_kind`
+  no longer lets a discussion start as a plain chat; it raises `SessionAttributionError` naming what to add.
+- **An entity has a recorded look and voice**: one record in its home holds its avatar and its voice, with a default
+  from birth and every change remembered (the entity is told when its look or voice changed). See
+  [docs/digital-identity.md](docs/digital-identity.md).
+- **An entity has a track record and a first reputation**: both are computed from what it has done (runs, outcomes,
+  tokens per kind of task); until feedback from people and agents exists, the reputation is the completion rate
+  only. See [docs/track-record.md](docs/track-record.md).
+- **An entity knows its acquaintances**: the entities and people it has interacted with are listed from its own
+  records, with when they first and last met. See [docs/track-record.md](docs/track-record.md#acquaintances). Full
+  list: [CHANGELOG.md](CHANGELOG.md).
+
 ## What's new in 0.17.0
 
 - **A host stop suspends a run, it never fails it**: a host that stops on purpose raises `EffectInterrupted` into
@@ -80,7 +102,7 @@ It is designed for long-running workflows that must survive restarts and explici
 - **Calibrated decisions**: an `LLM_CALL` whose output says `modality: "decision"` returns typed answers
   (`answers`, `decision`) from a decision model instead of generated text; `run_facade.decide(...)` runs one as a
   durable child run and the `decide` VisualFlow node asks a choice, yes/no or score question. Requires AbstractCore
-  2.32.0 or newer (AbstractRuntime 0.17.0 requires 2.33.0). See [docs/integrations/abstractcore.md](docs/integrations/abstractcore.md).
+  2.32.0 or newer (AbstractRuntime 0.18.0 requires 2.34.0). See [docs/integrations/abstractcore.md](docs/integrations/abstractcore.md).
 - **Conversational questions and guidance**: `ASK_USER` can ask an essential question (waits indefinitely) or a timed
   clarification with a declared fallback; `Runtime.steer(..., display_text=)` records human guidance in its exact
   words; opt-in public updates and tool-approval `public_action` context appear in the replay view.
@@ -161,7 +183,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.33.0 or newer (its light install:
+The base install includes AbstractCore 2.34.0 or newer (its light install:
 remote providers, tools, vision, voice, audio, music, and decision integration), plus the
 `abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
 default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/README.md

@@ -4,10 +4,32 @@
 
 It is designed for long-running workflows that must survive restarts and explicitly model blocking (human input, timers, external events, subworkflows) without keeping Python stacks alive.
 
-**Version:** 0.17.0 • **Python:** 3.10+
+**Version:** 0.18.0 • **Python:** 3.10+
 
 **Status:** pre-1.0 (API may evolve). For production use, pin versions and follow `CHANGELOG.md`.
 
+## What's new in 0.18.0
+
+- **Models unload after being idle**: a host sets how long a local model may sit unused (`set_model_idle_unload`,
+  AbstractCore's default 60 minutes; off with `None` or `0`); a running call is never interrupted and a model kept
+  loaded never unloads. `set_model_residency_locks` relays the host's "Keep loaded" set, and both come back after a
+  model-host restart. Loaded-model rows say when a model was last used, whether it is in use, who keeps it loaded
+  and when it unloads. Requires AbstractCore 2.34.0 or newer.
+- **A failed tool keeps its explanation**: a tool that reports its failure as a JSON object (a web search's backends,
+  bot-challenge status and hint) keeps it in the result, the run ledger and what the visual-flow Agent node shows
+  the model, after the error line.
+- **A store that cannot attribute a session is refused**: a custom run store whose index rows lack `session_kind`
+  no longer lets a discussion start as a plain chat; it raises `SessionAttributionError` naming what to add.
+- **An entity has a recorded look and voice**: one record in its home holds its avatar and its voice, with a default
+  from birth and every change remembered (the entity is told when its look or voice changed). See
+  [docs/digital-identity.md](docs/digital-identity.md).
+- **An entity has a track record and a first reputation**: both are computed from what it has done (runs, outcomes,
+  tokens per kind of task); until feedback from people and agents exists, the reputation is the completion rate
+  only. See [docs/track-record.md](docs/track-record.md).
+- **An entity knows its acquaintances**: the entities and people it has interacted with are listed from its own
+  records, with when they first and last met. See [docs/track-record.md](docs/track-record.md#acquaintances). Full
+  list: [CHANGELOG.md](CHANGELOG.md).
+
 ## What's new in 0.17.0
 
 - **A host stop suspends a run, it never fails it**: a host that stops on purpose raises `EffectInterrupted` into
@@ -29,7 +51,7 @@ It is designed for long-running workflows that must survive restarts and explici
 - **Calibrated decisions**: an `LLM_CALL` whose output says `modality: "decision"` returns typed answers
   (`answers`, `decision`) from a decision model instead of generated text; `run_facade.decide(...)` runs one as a
   durable child run and the `decide` VisualFlow node asks a choice, yes/no or score question. Requires AbstractCore
-  2.32.0 or newer (AbstractRuntime 0.17.0 requires 2.33.0). See [docs/integrations/abstractcore.md](docs/integrations/abstractcore.md).
+  2.32.0 or newer (AbstractRuntime 0.18.0 requires 2.34.0). See [docs/integrations/abstractcore.md](docs/integrations/abstractcore.md).
 - **Conversational questions and guidance**: `ASK_USER` can ask an essential question (waits indefinitely) or a timed
   clarification with a declared fallback; `Runtime.steer(..., display_text=)` records human guidance in its exact
   words; opt-in public updates and tool-approval `public_action` context appear in the replay view.
@@ -110,7 +132,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.33.0 or newer (its light install:
+The base install includes AbstractCore 2.34.0 or newer (its light install:
 remote providers, tools, vision, voice, audio, music, and decision integration), plus the
 `abstractruntime-mcp-worker` entry point. It keeps inference remote/light by
 default: local engines such as MLX, vLLM, HuggingFace/Torch, Diffusers, and

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/docs/README.md

@@ -44,6 +44,8 @@ In this repo, the AbstractCore wiring lives under `src/abstractruntime/integrati
 
 - `automations.md` — automations: a workflow run on a schedule, on an event or on request as a durable controller run; triggers (`schedule@1`, `schedule@2` calendar rules in a time zone, `manual@1`, `email.received@1`, `feed.item@1` RSS 2.0 / RSS 1.0 / Atom, `webhook.received@1` Standard Webhooks, entry-point sources), per-user trigger connections, the CloudEvents envelope (`input_data.event`), run origin (`_meta.origin`), wakes (`SCHEDULE_RUN`: work later in the same session, with at most the caller's tools), Publish to channel (`PUBLISH_EVENT`, alerts with `recipient` and `channels`), commands, independent or growing context, discussions forked at any occurrence (own writable workspace, the automation's workspace mounted read-only), tool approval, typed waits, notifications and retries, and the storage guarantees (create-if-absent, per-run lock, turn roots, session kinds, one writer process per store)
 - `entity-runtime.md` — per-entity runtimes for summoned entities: homes, the one-writer lease, act-only diary privacy (`$act_only` refs), durable visit waits with deadlines
+- `digital-identity.md` — an entity's look and voice: `identity.json` in the home, the recorded default, the `identity_changed` biography row, the identity reference on runs, the fingerprint, the summon cue
+- `track-record.md` — an entity's or a session's track record (sessions, runs, successes, failures, tokens) and reputation (trust per task kind with its evidence), computed from existing records; completion rates until feedback exists; and its acquaintances (the entities and humans it met)
 - `evidence.md` — artifact-backed evidence capture for external-boundary tools
 - `mcp-worker.md` — MCP worker CLI (`abstractruntime-mcp-worker`)
 - `replay.md` — the replay view: one reconstruction of a run tree (status, the interaction to answer, messages, one activity per execution, artifacts, usage, the workflow it executes) that every client renders; the durable cursor (`seq`, `list_after`); conformance fixtures

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/docs/api.md

@@ -459,7 +459,7 @@ Implementation: `src/abstractruntime/replay/` (ADR 0010). Guide: [replay.md](rep
 
 ### AbstractCore (LLM + tools)
 
-Requires: `pip install abstractruntime` (AbstractCore 2.33.0 or newer is part of the base install).
+Requires: `pip install abstractruntime` (AbstractCore 2.34.0 or newer is part of the base install).
 
 Implementation: `src/abstractruntime/integrations/abstractcore/*`.
 

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/docs/automations.md

@@ -1020,8 +1020,12 @@ Automations rely on four store guarantees. Hosts that bring their own store must
   chat. The JSON store also removes run temp files older than 10 minutes, left behind by a crash, when it opens.
 - **A run index for sessions.** `Runtime.start` checks the attribution of every root run that names a session. A
   store without a run index (no `session_kinds` and no `list_run_index`) cannot answer, and the start is refused with
-  `SessionAttributionError` rather than risk starting an unanchored run in a discussion session. Strict history reads
-  and `latest_occurrence` (which uses the store's `latest_occurrence_row`) need the index too.
+  `SessionAttributionError` rather than risk starting an unanchored run in a discussion session. A store whose
+  `list_run_index` rows do not carry `session_kind` (an index written before automations v1) cannot tell a discussion
+  from a chat either: its session-bearing starts are refused the same way, never started as a plain chat. To upgrade
+  a custom store, add `session_kind` and `role` to its index rows, or implement `session_kinds(session_id)`. The
+  built-in stores already do. Strict history reads and `latest_occurrence` (which uses the store's
+  `latest_occurrence_row`) need the index too.
 
 ### Crash safety
 

abstractruntime-0.18.0/docs/digital-identity.md

@@ -0,0 +1,184 @@
+# Digital identity (an entity's look and voice)
+
+Every entity has one digital identity: the avatar design the apps draw for it, the colour of that
+design, and the voice it speaks with. AbstractRuntime keeps it as one small file in the entity's
+home, `identity.json`, and owns its format and its writer
+(`abstractruntime.identity.digital_identity`). AbstractGateway checks what only it can check (the
+design is in the avatar catalog it loaded, the voice is offered and downloaded, the home is not
+held for maintenance) and then calls the runtime writer. Apps read the identity through the
+gateway. This page documents the runtime half; the decision record is the framework's ADR 0052.
+
+Identity says WHO the entity is. What it is doing right now (activity, poses) is a separate
+subject.
+
+## The record
+
+```json
+{
+  "schema_version": 1,
+  "rev": 2,
+  "avatar": {"style": "watch-vortex", "color": "#3a7bd5", "source": "chosen"},
+  "voice": {"provider": "abstractvoice", "model": "qwen3-tts", "voice": "fr-male-rene", "source": "chosen"},
+  "set_at": "2026-11-04T09:00:00+00:00",
+  "set_by": "user:laurent"
+}
+```
+
+| Field | Rule |
+|---|---|
+| `schema_version` | exactly 1 |
+| `rev` | 1 for the first record, one more for each write, never reused |
+| `avatar.style` | an abstractavatar design id: a lowercase letter, then up to 63 lowercase letters, digits or dashes |
+| `avatar.color` | `#rrggbb`, lowercase hex |
+| `avatar.source`, `voice.source` | `default` (the recorded default) or `chosen` |
+| `voice` | `provider`, `model` and `voice` together (each non-empty, at most 128 printable characters), optional `speed` (above 0, at most 4) and `quality_preset` (at most 32 characters); or `null` |
+| `set_at` | UTC time with its offset, set by the writer's clock |
+| `set_by` | `namespace:name` (for example `user:laurent`), `operator`, or `default` |
+
+`voice: null` is allowed only on the recorded default of a gateway that had no default voice
+(`set_by: default`, `avatar.source: default`). Such an entity has no voice and says so; it never
+borrows one. The whole file is at most 4096 bytes.
+
+A file the runtime cannot read in full raises `IdentityUnreadable`, on read and on write: a newer
+`schema_version`, broken JSON, a missing field, an unknown field, or a value out of bounds. It is
+never treated as "no identity", and the writer never overwrites it. A home without
+`identity.json` reads as `None`: its older `voice.yaml` and `appearance.json` are the gateway's to
+read, and the runtime never touches them.
+
+## Writing it
+
+```python
+from abstractruntime.identity import AvatarChoice, VoiceChoice, write_identity
+
+record = write_identity(
+    home_dir,
+    avatar=AvatarChoice(style="watch-vortex", color="#3a7bd5", source="chosen"),
+    voice=VoiceChoice(provider="abstractvoice", model="qwen3-tts", voice="fr-male-rene", source="chosen"),
+    set_by="user:laurent",
+    cause="chosen",
+    provenance="PUT /entities/castor/identity",
+    check=gateway_checks,  # optional: raise to refuse (catalog, offered voice, downloaded model)
+)
+```
+
+In this order: the current file is read; the new record gets the next `rev` and `set_at`; every
+bound is checked (`IdentityInvalid`, whose `field` names the bad value, for example
+`voice.speed`); `check(record)` runs; one row is appended to the home's biography; then the file
+is replaced atomically. A refusal before the row writes nothing.
+
+The biography is `<home>/state_history.jsonl`, the same append-only file and field names as the
+`phase_changed` rows, so one reader handles both:
+
+```json
+{"marker": "identity_changed", "rev": 2, "from": {...rev 1...}, "to": {...rev 2...},
+ "written_by": "user:laurent", "cause": "chosen", "at": "2026-11-04T09:00:00+00:00",
+ "provenance": "PUT /entities/castor/identity"}
+```
+
+The row is on disk before the file moves. If the file then fails to move, the old identity stays,
+the row stays, and the next write takes the rev after it: a rev is never given twice.
+`identity_at_rev(home_dir, n)` answers what the identity was at rev `n` from the current file or
+from these rows (a rev whose file never landed raises `LookupError`), so a copied home knows every
+look and voice it ever had. `life_sleep_stats` skips these rows like every other marker row.
+
+One write at a time per home: every write holds `<home>/.identity.lock` from its first read to
+the file replace, and a second writer (another thread, another process, the gateway's start-up
+pass racing a change from an app) waits its turn. Two writers never read the same rev, so a rev
+is never given twice, and two default passes racing on one home write it once. The check hook
+runs under the lock: keep it short. The lock file is never removed.
+
+## The recorded default
+
+Every entity has a look and, when the gateway has a default voice, a voice from day one. The
+default is recorded, never computed again at read time: once written it does not change when the
+gateway's default voice changes.
+
+`default_identity(entity_id, gateway_default_voice)` returns `(avatar, voice)`; it is pure (no
+clock, no randomness), so anyone can recompute it:
+
+- seed = SHA-256 of the entity id exactly as the manifest records it (`entity:castor`, or the
+  older `entity:castor@<home_id>`);
+- design = `DEFAULT_STYLE_POOL[seed[0] % 8]`, the pool being, in this order: `watch-halo`,
+  `watch-vortex`, `watch-nebula`, `watch-rings`, `watch-galaxy`, `watch-lotus`, `watch-crystal`,
+  `watch-aurora` (all eight have a Watch drawing in abstractavatar 0.1.1);
+- colour = HSL(hue = (seed[1] × 256 + seed[2]) mod 360, saturation 62 %, lightness 52 %), each RGB
+  channel = floor(c × 255 + 0.5), written `#rrggbb`;
+- voice = the gateway's default voice `{provider, model, voice, speed?, quality_preset?}` as a
+  value, or `None` when it has none;
+- `source: default` on both parts.
+
+Worked example: for `entity:castor` the seed starts `0x1a 0x92 0x51`, so the design is
+`26 % 8 = 2` → `watch-nebula` and the hue is `(146 × 256 + 81) % 360 = 17` → `#d06439`.
+
+`record_default_identity(home_dir, entity_id=..., gateway_default_voice=..., provenance=...)`
+writes it as the home's first record (`set_by: default`, biography `cause: recorded_default`) and
+returns `(record, True)`; on a home that already has a record it returns `(record, False)` and
+writes nothing. The gateway calls it at birth, once per existing home when it starts, and on the
+first read of a home that start skipped.
+
+## The reference
+
+Apps name an identity by reference, never by a copy of its values: `{"of": <subject>, "rev": <n>}`,
+string form `<subject>#<n>`.
+
+```python
+from abstractruntime.identity import identity_ref, parse_identity_ref
+
+ref = identity_ref("entity:castor", 3)
+str(ref)                                 # "entity:castor#3"
+parse_identity_ref("session:sess_9f2a#1")  # a regular agent's identity rides its session
+```
+
+`parse_identity_ref` refuses anything else (`castor`, `entity:castor`, `entity:castor#0`,
+`entity:castor#03`). On a run the reference rides `vars["_runtime"]["identity_ref"]` as
+`{"of", "rev"}`, beside the signed entity stamp (`vars["_runtime"]["entity"]`) and never inside
+it: presentation is not authority. `stamp_run_identity_ref(vars, ref)` puts it there;
+`read_run_identity_ref(vars)` returns it, or `None` when the run carries none (a reference is never
+made up). An old rev resolves through `identity_at_rev`.
+
+## The fingerprint
+
+`identity_fingerprint(manifest, book_head=diary.head())` names the individual:
+`actor_id = ActorFingerprint.from_metadata(kind="entity", display_name=<slug>,
+metadata={entity_id, home_id, spark_hash}).actor_id` (`ar_` + 24 hex), served with the continuity
+receipts the home already has: `spark_hash` (the seed), `home_id` (the individual) and `book_head`
+(the diary's chain head). It is derived on every read and stored nowhere. A copy of a home with a
+new `home_id` is a different individual with a different `actor_id`. There are no keys and no
+signatures.
+
+## The summon cue
+
+At a summon the entity is told, in one sentence, about the change that made its current identity:
+
+- "You were given your look and voice today." (the first record)
+- "You were given your look today; you have no voice yet." (a first record without a voice)
+- "Your voice changed on 4 November (by laurent): now fr-male-rene."
+- "Your look changed today (by the operator): now watch-lotus in #aa3344."
+- "Your look and voice changed today (by laurent): now watch-vortex in #3a7bd5, voice en-female-amy."
+
+`identity_change_cue(home_dir, since=...)` returns that sentence, or `None`. It speaks of the
+biography row of the current rev (never of a row whose file did not land), and only when that row
+is newer than `since`, the previous summon's time; with `since=None` (the caller knows no previous
+summon) it is always told. Dates are UTC.
+
+`render_summon_prelude(..., home_dir=..., identity_since=...)` puts the sentence after the
+identity core and before the diary tail, as a section that may be dropped to fit the budget (it is
+fitted first). The prelude stays a pure read. The chat driver (`ChatSession(...,
+identity_since=...)`) and the durable visit workflow (`build_visit_workflow(...,
+identity_since=...)`, or `_visit.identity_since` seeded by the door at run creation, which wins)
+pass the summon's home. An unreadable identity is named in the prelude's warnings; it does not
+stop the summon.
+
+The diary stays the entity's own record: nothing here writes a diary entry. The entity may write
+one itself after hearing the cue.
+
+## Tests
+
+`tests/test_digital_identity.py` (`-m basic`): the round trip and the row shape, every bound
+naming its field, unreadable files refused on read and on write, the row before the file, the rev
+never reused, the default rule against an independent HSL computation and a worked value, the pool
+order, purity over 1000 calls, two homes of one spark getting different colours, the pool checked
+against abstractavatar's catalog (skipped when the package is not installed), idempotent default
+writes, the reference format and its place beside the stamp, the fingerprint formula, the cue
+sentences and the `since` rule, and the cue in place in the prelude, the chat driver and the visit
+workflow.

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/docs/entity-runtime.md

@@ -15,6 +15,9 @@ entities/castor/
   manifest.json            # entity_id (birth marker — never a lookup key)
   spark.yaml               # the attested seed
   substrate.yaml           # operator's ONE mind choice (provider+model)
+  identity.json            # look and voice (digital-identity.md)
+  .identity.lock           # one identity write at a time
+  state_history.jsonl      # biography: state, phase_changed and identity_changed rows
   memory.sqlite3           # graph + journal (abstractmemory)
   home.sqlite3             # diary book + command inbox
   runtime_castor.sqlite3   # run store + ledger (THIS page)

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/docs/getting-started.md

@@ -12,7 +12,7 @@ Remote-light runtime:
 pip install abstractruntime
 ```
 
-This installs AbstractCore 2.33.0 or newer with remote provider, vision,
+This installs AbstractCore 2.34.0 or newer with remote provider, vision,
 voice, audio, music, decision, tool, and MCP-worker support. The base install is
 remote-light: it can route multimodal workflows to hosted or OpenAI-compatible
 endpoints, but it does not select local inferencer stacks such as MLX, vLLM,

{abstractruntime-0.17.0 → abstractruntime-0.18.0}/docs/integrations/abstractcore.md

@@ -16,7 +16,7 @@ Implementation pointers (this repo):
 pip install abstractruntime
 ```
 
-The base install includes AbstractCore 2.33.0 or newer. That is the supported baseline for the `decision` output modality (the `output.decision` route and `/v1/decisions`), the current server auth split (`Authorization` for server auth, `X-AbstractCore-Provider-API-Key` for provider overrides), generated-media contracts, image upscaling, capability catalog, prompt-cache control-plane endpoints (including session attribution via `/acore/prompt_cache/key_meta`), host memory snapshots, the host-wide loaded-model sweep used by residency listings, the process-wide MLX residency report and eject used by model unload, durable bloc prompt-cache helpers, bindings and lifecycle operations, task-aware model residency for text/image/video/TTS/STT, current tool catalog, AbstractCore's public output-selector contract, async/sync text-generation output-selector parity, video generation endpoints, the public local vision-cache catalog helper used by Runtime discovery, vision adapter discovery plus batch/LoRA media controls, and the released shared workspace/file-filter utility surface used by Runtime packaging and integration checks.
+The base install includes AbstractCore 2.34.0 or newer. That is the supported baseline for the idle unload (`set_model_idle_unload`, residency rows with `last_used_at`, `in_use`, `locked_by`, `idle_unload_at`), the `decision` output modality (the `output.decision` route and `/v1/decisions`), the current server auth split (`Authorization` for server auth, `X-AbstractCore-Provider-API-Key` for provider overrides), generated-media contracts, image upscaling, capability catalog, prompt-cache control-plane endpoints (including session attribution via `/acore/prompt_cache/key_meta`), host memory snapshots, the host-wide loaded-model sweep used by residency listings, the process-wide MLX residency report and eject used by model unload, durable bloc prompt-cache helpers, bindings and lifecycle operations, task-aware model residency for text/image/video/TTS/STT, current tool catalog, AbstractCore's public output-selector contract, async/sync text-generation output-selector parity, video generation endpoints, the public local vision-cache catalog helper used by Runtime discovery, vision adapter discovery plus batch/LoRA media controls, and the released shared workspace/file-filter utility surface used by Runtime packaging and integration checks.
 
 The base install also includes the remote-light media/capability plugins needed
 for AbstractCore's multimodal `generate(..., output=...)` path. Local
@@ -922,7 +922,9 @@ except core.HostActionRefused as refused:
 - Chat compaction summarizes a run with the model the run uses. Only a run with no model of its own is summarized with the current default model; the summarizer does not keep the model that was the default at startup.
 - A load with `ttl_s` or `keep_alive` for an in-process model, or for a model that is already loaded, lists them under `unsupported_options` with a warning. A load that fails part-way unloads what it loaded.
 - Changing a capability default (image, voice, music) unloads the models the old capability routes had loaded before the new routes take effect.
-- MLX has no idle or time-based unload. A load with `ttl_s` or `keep_alive` on MLX reports them under `unsupported_options`, with a warning, and the model stays loaded until it is unloaded.
+- An in-process model (MLX, transformers, GGUF) has no per-load TTL: a load with `ttl_s` or `keep_alive` reports them under `unsupported_options`, with a warning. AbstractCore's idle unload applies instead (ADR 0012): a model no call has used for the idle-unload time (60 minutes by default) is unloaded; a locked model never is, and a running call is never interrupted. The next call loads it again.
+- `set_model_idle_unload(seconds)` (host facade and both local clients) sets that time for the process; `None` or `0` turns it off. A refused value (negative, not a number) answers `ok: false` and leaves the setting unchanged. Local residency rows of in-process text models carry `idle_unload_s`, `last_used_at` and `idle_unload_at` (epoch seconds; `None` when the setting is off, the model is locked or a call is running), and Core's `in_use` (a call is running on it) and `locked_by` (the owners whose lock keeps it loaded, other accounts included), passed through unchanged.
+- `set_model_residency_locks(locks)` makes the locked models exactly `locks` (`[{"provider", "model"}]`): listed models that are resident are locked, missing ones are loaded then locked, the others are unlocked; each pair reports its own outcome. A lock names a provider and a model; the `base_url` of a configured endpoint is not part of the key. A host stores its "Keep loaded" set and calls it at start. Both setters are `set_` names, so a host that rebuilds its client (the gateway's model host after a restart) replays them.
 
 ## Model residency locks and context estimates