From c43bd46ecb99a257e8ed2cecb2d3876448d0cee3 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Tue, 22 Sep 2026 16:53:27 +1000 Subject: [PATCH] docs(news): state what a reader gets, and move the design where it is read The v1.36.0 release note carried four things a reader cannot use. The dashboard's seven in-browser tools and the installtype fix stay; the withheld judgement verbs, the consequentialHint limitation and the two silent-failure notes are removed from the release feed and moved to where an implementer looks. - The four verbs are withheld because an agent that can approve can approve its own work. That is settled design, so it now sits in docs/architecture/identity.md, beside the approval-path conflict it belongs with, stated as the constraint it is: attribution, not capability, is what releasing them depends on. - The browser-tool surface had no home in docs/architecture, so it has one now: docs/architecture/dashboard-agent-tools.md holds what a tool call can be attributed to, why confirmation is a signal rather than a control, and the two ways the surface fails silently. Audited 1.35.0, 1.36.0 and 1.37.0 for the same class. 1.37.0 is clean. 1.35.0 carried two build notes: a bullet recounting that a guard had never been written because it failed, and a clause about a manager "finally" having a production writer. Both are gone; the capabilities they were attached to remain. RELEASING.md now carries the rule so the next release reads it: release notes state what a reader gets, and design constraints, withheld capabilities and failure modes belong in docs/architecture/, because a note about an absence reads as a feature to someone who never had the thing. docs/news/** is regenerated by task news, never hand-edited. task check passed before this commit: the chain runs it, so a failing gate commits nothing. --- CHANGELOG.archied.md | 30 +---------------- RELEASING.md | 10 +++++- docs/architecture/dashboard-agent-tools.md | 39 ++++++++++++++++++++++ docs/architecture/identity.md | 14 ++++++++ docs/data/generated/dev-docs.json | 12 ++++++- docs/news/archied/1.35.0.md | 7 +--- docs/news/archied/1.36.0.md | 23 ------------- docs/news/releases.json | 4 +-- 8 files changed, 77 insertions(+), 62 deletions(-) create mode 100644 docs/architecture/dashboard-agent-tools.md diff --git a/CHANGELOG.archied.md b/CHANGELOG.archied.md index 1c03a8133..058c16124 100644 --- a/CHANGELOG.archied.md +++ b/CHANGELOG.archied.md @@ -57,29 +57,6 @@ agent's call and a page script's call reach the server identically. Tools therefore record the signed-in identity and a source, and **never** that an agent acted. -### The four judgement verbs are deliberately absent - -- `approve`, `reject`, `abandon` and `archive` are **not** exposed. `internal/domain/taskactions` - records only a source string and stamps `KindHumanApproved`, so an agent's approval would be written - down as a person's. An agent that can approve can approve its own work, and the one control this - design exists to keep is a human accepting it. Those verbs land once task actions carry both the - acting identity and the authorising principal. - -### `consequentialHint` does not gate anything, and the release says so - -- Chrome 152 accepts `consequentialHint` at registration and **omits it from `getTools()`**, so no - client sees it and the browser cannot enforce what it does not surface. The three recovery tools - instead require an explicit `confirm: true`, which is a **deliberate-action signal rather than a - security control** an agent can trivially satisfy. The boundary that holds is the session: the tools - cannot exceed what the signed-in operator can already do. - -### Two ways this fails silently, now recorded next to the code - -- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is absent *even - with the flag*, and nothing reports why. `mkcert` covers local development. -- **`archie-ui` embeds `ui/dist` into its binary**, so rebuilding the distribution is not deploying it; - a running process can serve a bundle with no tools while the built one has them. - ### Binaries built by the development build task can be updated - `task build` passed the `installtype` stamp for three of six commands, so `archie-messaging`, @@ -97,10 +74,6 @@ `internal/app/controlplane`; the client half now lives in `internal/infrastructure/controlplanerpc`, and the app package keeps the server, the registry, the seeds, the validators and the schema derivation. -- **The PRD's guard now exists, and passes:** `cmd/archie-messaging/architecture_test.go` measures the - linked binary against the banned list, with `internal/domain/workflow/task` as an exception checked - in both directions. Before this the guard had never been written -- because it failed. A messaging - process linking a SQLite driver and the workflow engine is a severance hole, not a design choice. - The resource documents are type-aliased back into the app package, so there is one definition read under two names rather than a copy per side. @@ -108,8 +81,7 @@ - The Messaging Service reports each channel's state, recorded **per channel**: one channel's failure marks only itself, a channel that cannot start is marked failed **with its reason** rather than only - logged, and one that returns is marked stopped. `internal/channels/status.Manager` finally has a - production writer. + logged, and one that returns is marked stopped. `internal/channels/status.Manager` reports each channel's state. - `PutChannelStatus`/`ListChannelStatus` carry that to the dashboard, following the config-snapshot split. The store **replaces the reported set**, so a channel the reporter stops mentioning is deleted rather than left as a stale `running`; an empty report clears the table, because hosting no diff --git a/RELEASING.md b/RELEASING.md index 3682ab2af..3f50f90c1 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -41,7 +41,15 @@ needs the new agent image to actually take effect, say so explicitly and either cut an agent release or note that `docker compose build agent` / `docker compose pull agent` is needed separately. -## Process +## What the notes are for + +**Release notes state what a reader gets.** A reader scanning releases does not +need to know what was withheld, what a browser API cannot do, or what the +engineering took; and a note about an absence reads as a feature to someone who +never had the thing. Design constraints, withheld capabilities and failure modes +belong in `docs/architecture/`, where implementers look, because there they are +requirements rather than news. + ```bash task release:preview VERSION=1.3.0 # preview what would land, both components diff --git a/docs/architecture/dashboard-agent-tools.md b/docs/architecture/dashboard-agent-tools.md new file mode 100644 index 000000000..de332cd33 --- /dev/null +++ b/docs/architecture/dashboard-agent-tools.md @@ -0,0 +1,39 @@ +# The dashboard's tools for an in-browser agent + +The dashboard registers in-browser tools an agent can call through the page's model +context. Four are read-only — `list_tasks`, `get_task`, `recent_events`, +`daemon_health` — and three recover stuck work: `retry_task`, `stop_task`, +`cancel_task`. Each wraps the same `ui/src/lib/api.ts` client the dashboard itself +calls, so an agent and a person exercise one path rather than two. + +The four judgement verbs are withheld for the reason `identity.md` gives: an agent +that can approve can approve its own work. + +## What a tool call can be attributed to + +A page can invoke its own tools, so an agent's call and a page script's call reach +the server identically — the difference does not exist on the wire, and no header +recovers it. A tool call is therefore attributed to the signed-in identity the +request presented, with its source recorded as a hint; it never records that an +agent acted, and it never records that a human approved. An agent's action is +attributable only on a surface where the agent presents its own credential. + +## Confirmation is a signal, not a control + +The three recovery tools require an explicit `confirm: true`, which makes a +consequential call deliberate rather than incidental. It is not a security control: +an agent can trivially satisfy it, and the browser cannot enforce +`consequentialHint` at all — Chrome accepts it at registration and omits it from +`getTools()`, so no client can see what the browser does not surface. + +The boundary that holds is the session. These tools cannot exceed what the operator +signed in at the provider is already permitted to do. + +## Two ways the surface fails silently + +- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is + absent even with the flag enabled, and nothing reports why. `mkcert` covers local + development. +- **The dashboard embeds `ui/dist` into its binary.** Rebuilding the distribution is + not deploying it: a running process can serve a bundle without tools while the + built one has them, or serve a bundle older than its own binary. diff --git a/docs/architecture/identity.md b/docs/architecture/identity.md index 7144fc6e2..c689cc7f0 100644 --- a/docs/architecture/identity.md +++ b/docs/architecture/identity.md @@ -263,6 +263,20 @@ identity. ## Current enforcement and isolation +## Withheld judgement verbs + +`approve`, `reject`, `abandon` and `archive` are not exposed to an agent. An agent +that can approve can approve its own work, and the one control this surface exists +to keep is a human accepting it. + +The constraint is attribution, not capability: a task action records the acting +identity and the authorising principal, so exposing the verbs requires that an +agent's action be recorded as an agent's and the authority it used recorded +separately. Until a surface carries both, the verbs stay withheld. This is the +reason the four verbs are absent from the dashboard's in-browser tools, and it is +why releasing them is a change to this boundary rather than a change to the tools. + + The current implementation uses identity equality as an authorization check for chat task approval and cancellation. This conflicts with the approved rule that identity is attribution rather than authentication or access control and must be diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 1d1700dbe..010d5bdf3 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -30,6 +30,12 @@ "section": "Architecture", "body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nindexing settings, provider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetime of the application. Any value that may legitimately change while\nthe application is running, between application instances, or between\ndeployments is not a constant.\n\nA runtime setting may have a default, but the default is not its only access\npath. The owner exposes a typed settings structure, validation, and a\n`DefaultSettings` constructor or equivalent. Private constants used to implement\ndefaults do not turn those defaults into invariants and MUST NOT be consumed\ndirectly by runtime code.\n\nEach runtime setting and policy value MUST declare:\n\n- its owner;\n- type, units, validation constraints, and safe bounds;\n- default and derivation, if any;\n- whether it is startup-only, live-reloadable, or restart-required;\n- whether it may differ by installation, identity, repository, workflow,\n channel, or plugin instance;\n- whether it is secret, sensitive, or safe to report;\n- its current source, effective value, version, and last-known-good version;\n- the command and identity required to change it.\n\n## Current configuration migration ledger\n\nThis ledger records the current meanings hidden inside `internal/config`. It is\nthe source inventory for dissolving that package; rows are split where the\nexisting structure combines different owners.\n\n| Current values | Current location | Target owner and requirement |\n| ----------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `WorkDir`, `DBPath` | root `Config` | Workspace/storage infrastructure settings. `DBPath` is the prefix for independent task and conversation SQLite files. Defaults derive from the platform data directory. |\n| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |\n| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |\n| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |\n| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |\n| `DiffCapLines` | root `Config` | Agent-change policy value. |\n| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |\n| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |\n| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |\n| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |\n| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |\n| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |\n| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |\n| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |\n| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |\n| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |\n| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |\n| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |\n| listen/relay addresses | email config | Email adapter instance settings. |\n| webhook target | `Notify` | Notification adapter instance settings. |\n| web listen address | `Web` | Web transport settings. |\n| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |\n| index directory and database path | `Indexing` | Index infrastructure settings, derived from storage settings unless explicitly overridden. |\n| forge, dispatch, models, providers, containers, memory, tools, indexing and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |\n| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |\n| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |\n| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |\n\n## Behavioural literals and incorrectly fixed values\n\nThe following current values affect useful behaviour but are not represented as\nowned typed settings or policy. They MUST be classified and migrated before the\nold configuration package is removed. The listed target is the architectural\ndecision; exact setting names are implementation details.\n\n| Capability | Values fixed in current code | Required classification |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Chat agent | maximum steps `8` in `cmd/archied` | Workflow/chat execution policy. |\n| Context compression | enabled, threshold `0.5`, context size `128000`, protect first `3` and last `20`, compression marker, token estimate of four characters per token | Model/context runtime settings. The marker is presentation; the estimate is provider/model strategy, not a universal truth. |\n| Tool guardrails | escalation thresholds `3`, `5`, `10`, `2` | Tool-use policy with named meanings and bounded defaults. |\n| Tool output | per-result cap `50000` characters, no aggregate turn cap, preview `500` characters | Tool-execution resource and presentation settings. Per-result spill/truncation remains; turn continuation is not character- or token-gated. |\n| Pairing/access | code TTL `1h`, maximum pending `3`, rate window `10m`, failures `5`, lockout `1h`, maximum lockout `24h` | Access policy. Code length/alphabet and salt length require an explicit security-constraint decision; they are not automatically valid constants. |\n| NATS daemon consumer | stream `ARCHIE_TASKS`, consumer `archie-daemon`, deduplication `2m`, poll `2s`, deliveries `3`, acknowledgement wait `5m`, inactive threshold `24h`, subjects | NATS topology settings plus delivery policy. Subject grammar or protocol headers may be invariants only if declared as versioned wire contracts. |\n| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |\n| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |\n| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |\n| Indexing | build timeout `10m`, metadata timeout `5s` | Index operation policy. |\n| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |\n| Memory read path | per-scope record limit `20`, rendered `\u003cmemory\u003e` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |\n| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |\n| Memory safety scanner | compiled prompt-injection and sensitive-data patterns with fixed warn/block consequences | Versioned memory-domain policy definitions. Patterns and consequences must be inspectable and replaceable without editing scanner code. |\n| MCP stdio | initial backoff `500ms`, maximum backoff `30s`, unlimited default retries, send and shutdown `5s` | MCP transport retry, request, and lifecycle policy. Unlimited retries must be explicit rather than a zero-value accident. |\n| MCP SSE/HTTP | reconnect `1s` to `30s`, POST/request timeout `30s` | MCP transport settings and retry policy. |\n| Message framing | MCP frame `4MiB`, worker protocol frame `8MiB`, diagnostic `64KiB`, media/base64 `64MiB` | Resource/security policy unless a published wire protocol mandates the limit. Limits must be configurable only within safe bounds. |\n| Webhooks and web UI | webhook bind `0.0.0.0:8644`, webhook shutdown `5s`, web read-header `5s`, web shutdown `2s` | Transport instance and lifecycle settings. |\n| Telegram | typing refresh `4s`, draft interval `700ms`, update-action TTL `10m` | Telegram adapter presentation and lifecycle settings. |\n| Telegram limits | message length `4000` and callback/update prefixes | Record the upstream platform constraint and version it as an adapter compatibility limit; prefixes may remain wire constants when changing them would invalidate outstanding callbacks. |\n| Containers | stop and pull timeouts `10s` and `30s` | Container lifecycle policy. |\n| HTTP clients | feasibility notification timeout `10s`; other paths use `http.DefaultClient` | Adapter request policy. Every outbound client requires an explicit timeout profile. |\n| Workflow routing | labels `bug`, `feature`, `bootstrap`; workflows `tdd`, `feasibility`, `bootstrap`; fallback `implement` | Agent-system routing policy. Workflow identifiers are references, not compiled routing decisions. |\n| Filesystem/deployment | `.agents/skills`, `.archie/stages`, `.archie/gate.go`, `/data/worktree`, `/data/repo`, cache names/paths and prepared sentinel | Split into deployment settings, repository conventions, and genuine internal protocol markers. Paths an installation may relocate are settings. |\n| Packaged release data | `/usr/share/archie/CHANGELOG.archied.md` and `/usr/share/archie/CHANGELOG.archie.md` | Packaging/deployment settings or paths derived from an installation prefix. |\n| Forge presentation | default label colour `bfd4f2` and state-label colours | Forge adapter presentation settings. |\n| Fallback system prompt | compiled fallback prompt | Agent-system default content, versioned and replaceable through its owning settings; safety constraints remain policy/code. |\n| Default paths and identities | config path, data paths, listen addresses, model roles and workflow names | Typed defaults belonging to their respective owners, never global constants consumed throughout the application. |\n\nThis inventory is intentionally broader than exported Go `const` declarations. A\nliteral hidden in a constructor, timeout, switch, retry loop, path join, prompt,\nlabel map, or client setup restricts behaviour just as effectively as an\nincorrectly used constant.\n\n## Constants that may remain\n\nA value may remain constant only when its owner documents why runtime variation\nwould be invalid. Typical valid cases are:\n\n- domain enum values and state names;\n- a versioned wire-protocol version or framing token;\n- reserved internal headers and callback prefixes that peers must interpret\n identically;\n- compile-time mathematical relationships;\n- sentinel errors and internal type identifiers.\n\nNames such as a stream, consumer, label, workflow, file, directory, network,\nmodel role, timeout, retry count, capacity, size limit, colour, prompt, command,\nor executable are not invariants merely because the current application has only\none of them.\n\nArchitecture tests SHOULD reject exported behavioural constants outside approved\ninvariant packages and SHOULD detect direct consumption of private default\nconstants outside their owning `DefaultSettings` construction.\n\n## Current mutation and reload ledger\n\nThe application currently changes behavioural values through unrelated paths:\n\n| Current change seam | Current behaviour | Required target |\n| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |\n| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |\n| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |\n| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |\n| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |\n| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |\n| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |\n\nAny further mutation seam discovered during migration MUST be added here before\nit is changed. Direct field assignment on a live settings object is prohibited.\n\n## Universal change protocol\n\nChanging configuration is an application command performed by an identity. It\nMUST:\n\n1. resolve the target owner and current version;\n2. parse into that owner's typed settings;\n3. validate syntax, semantic constraints, policy, references, and safe bounds;\n4. stage a candidate without altering the active value;\n5. run owner-defined readiness and health checks;\n6. atomically promote the candidate and record actor, source, reason, diff,\n prior version, and new version;\n7. observe the affected capability for a bounded period;\n8. retain the new version on success, or automatically restore last-known-good\n on failure;\n9. report the rejected or rolled-back candidate without terminating unaffected\n capabilities.\n\nStartup loading uses the same candidate rules. A bad user value therefore does\nnot partially mutate the application or make a previously healthy capability\nunavailable.\n\nSettings that cannot safely reload in-process are marked restart-required. The\nchange may still be validated and versioned immediately, but promotion occurs\nthrough a controlled restart with the same health and rollback semantics.\n\n## Implemented runtime reload and settings writes (2026-09)\n\nTwo mechanisms change behavioural values at runtime: SIGHUP re-reads the file\nconfig, and the control plane owns every database-backed setting. The dashboard\nruntime overlay that used to sit between them was deleted once the control plane\ncovered its surface; `-config-overlay` names a file overlay and is unrelated.\n\n### Published snapshot: `config.Holder`\n\nThe running configuration is a published snapshot held in `config.Holder`\n(`internal/config/holder.go`). Get returns a value under RLock; Set replaces the\nwhole snapshot. A published Config is immutable: reload constructs a fresh one\nand calls Set. `config.Clone` deep-copies every reference-type field so a failed\ndecode cannot mutate the published snapshot's shared maps. `Holder.Get` panics\non a nil receiver — a forgotten `NewHolder` must fail loudly, not boot a daemon\nthat silently runs on an empty config.\n\n### The reloadable-field criterion\n\nThe diff-and-warn on reload asks whether a changed field takes effect without a\nrestart. The criterion is: **a field is reloadable when every consumer re-reads\nit.** That question read as \"what does the daemon re-read\" while the daemon owned\nthe only Holder; it stopped being sufficient when webui began sharing that\nHolder, because webui handlers re-read on every request. The allowlist lives in\n`cmd/archied/reload.go` and is deliberately a deny-by-default list: a field added\nto Config later defaults to requires-restart, forcing whoever adds it to decide\ndeliberately. A reload that changes any non-allowlisted field logs\n\"requires a restart\" with the field names; a fully-applied reload logs Info.\n\n### SIGHUP reload\n\nSIGHUP re-resolves the file config, re-applies the database layer over it\n(`boot.runtimeConfig`, the same call boot makes), validates, and atomically\nrepublishes through the shared Holder. A failed reload keeps the running config\nand records `last_error`/`last_error_at` in `/api/config` so the stale state is\nvisible where the operator is looking. The three poll tickers re-read\n`PollInterval` per iteration and reset on change, so a reloaded interval\ngenuinely takes effect.\n\n### Settings writes go through the control plane\n\nDatabase-backed settings are read and written through\n`ControlPlaneService` on the State Store's gRPC server: catalog, query,\ncommand, watch. Each feature owns its resource's validation and commands;\nstorage writes versions and audit records only. `docs/prds/runtime-control-plane.md`\nis the specification.\n\nTwo properties matter to anyone changing this area:\n\n- **Bootstrap stays file-owned.** The daemon reads the file config first and\n layers database resources over it at boot (`boot.loadRuntimeConfig`). Values\n the daemon needs before it can reach the State Store — the database path,\n listen addresses, credentials — stay file-only by design.\n- **Reload re-reads them.** SIGHUP resolves the file document and then runs the\n same `boot.runtimeConfig` layering boot does, so a reload cannot revert a\n database-owned setting to its file value. A control plane that cannot answer\n fails the reload rather than publishing the file's values over the running\n ones. Workflow execution budgets arrive on a watch rather than in a resource\n query, so boot records the last published settings and the reload re-applies\n them from there.\n\n## Completion criteria\n\nThe configuration rearchitecture is complete only when:\n\n- `internal/config` no longer exists;\n- every behavioural value has one classification and owner;\n- every current field and hard-coded value in the ledgers has a recorded\n disposition;\n- domains and plugins receive only their typed settings;\n- all changes use semantic commands and the universal change protocol;\n- active, candidate, rejected, rolled-back, and last-known-good versions are\n queryable with secret-safe provenance;\n- generated documentation lists every external key, default, constraint,\n mutability class, owner, and deprecation;\n- architecture tests prevent a new central runtime configuration model, direct\n live-setting mutation, and incorrectly fixed behavioural values.\n\n## Startup policy: missing credential degrades, invalid config is fatal\n\nDecided 2026-07-30. Recovered 2026-08-09 from the pre-migration issue tracker.\n\nA missing **credential** disables a capability. Only an **invalid config** stops\nthe daemon. \"Forge is a feature, not a requirement.\"\n\nBefore `518a1a0`, an unresolvable forge token did `return 1` in\n`cmd/archied/main.go`, so a chat-only user who never configured GitHub got no\nchat, no gateway, nothing — and under a systemd unit with `Restart=on-failure`\nand no start limit it crash-looped every five seconds with the error scrolling\npast unread. Forge construction now lives in `resolveForge`, shared by the\nprimary forge and every configured identity, and degrades to `forge.NewNoop`\nwith a warning. The identity path had the same defect and was worse: one\nidentity's missing credential killed all the others.\n\nMalformed configuration still fails fast in `configuration.Validate`, well\nbefore this point. That distinction is the whole design.\n\nApply the same reasoning to any future capability credential, LLM keys\nespecially: start, report the capability as unavailable, let the operator see it.\nGuarded by `TestResolveForgeDegradesInsteadOfFailing`.\n\n**Known consequence, tracked separately:** `worktree.Manager` still receives the\nempty token, so pushes fail late rather than at startup.\n\n## Config generation belongs to `archied setup`, not `install.sh`\n\nDecided 2026-07-30 ([#368](https://github.com/samcharles93/archie-core/issues/368)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n`install.sh` must stop generating `config.toml`; `archied setup` owns it. The\ninstaller hand-rolling TOML has already drifted from the schema once: the\ngenerated-config branch hardcoded `key = ARCHIE_GITHUB_TOKEN` and\n`host = ${GITEA_URL}` regardless of the answers given, so choosing Gitea produced\na config naming a token the installer never wrote (archied then exited 1), and\nchoosing GitHub pointed `host` at `gitea.example.com`. `61a5b35` patched this\nwith a `forge_block` shell helper shared by both config paths — that helper is a\n**workaround**, deleted by\n[#72](https://github.com/samcharles93/archie-core/issues/72). The durable fix is\nthat the code writing the config is the code that reads it.\n\nWhy Go and not Python: the installer must run where nothing is installed yet, and\n`python3` with `tomllib` means 3.11+, which is not safe on LTS distros. `archied`\nis already being built two steps earlier.\n\n**Key constraint for the port:** `BurntSushi/toml` does **not** survive a\ndecode/encode round trip with comments intact, and `config.example.toml` carries\ndocumentation users are meant to hand-edit. Decide the write strategy\n([#412](https://github.com/samcharles93/archie-core/issues/412)) before writing\nany prompting code. Do not port a separate `config.yaml`/`auth.yaml` secret\nsplit — Archie already has `secret.SecretRef{engine,key}`, so setup writes the\nreference to TOML and the value to the secret engine.\n" }, + { + "url": "/dev/architecture/dashboard-agent-tools/", + "title": "The dashboard's tools for an in-browser agent", + "section": "Architecture", + "body": "# The dashboard's tools for an in-browser agent\n\nThe dashboard registers in-browser tools an agent can call through the page's model\ncontext. Four are read-only — `list_tasks`, `get_task`, `recent_events`,\n`daemon_health` — and three recover stuck work: `retry_task`, `stop_task`,\n`cancel_task`. Each wraps the same `ui/src/lib/api.ts` client the dashboard itself\ncalls, so an agent and a person exercise one path rather than two.\n\nThe four judgement verbs are withheld for the reason `identity.md` gives: an agent\nthat can approve can approve its own work.\n\n## What a tool call can be attributed to\n\nA page can invoke its own tools, so an agent's call and a page script's call reach\nthe server identically — the difference does not exist on the wire, and no header\nrecovers it. A tool call is therefore attributed to the signed-in identity the\nrequest presented, with its source recorded as a hint; it never records that an\nagent acted, and it never records that a human approved. An agent's action is\nattributable only on a surface where the agent presents its own credential.\n\n## Confirmation is a signal, not a control\n\nThe three recovery tools require an explicit `confirm: true`, which makes a\nconsequential call deliberate rather than incidental. It is not a security control:\nan agent can trivially satisfy it, and the browser cannot enforce\n`consequentialHint` at all — Chrome accepts it at registration and omits it from\n`getTools()`, so no client can see what the browser does not surface.\n\nThe boundary that holds is the session. These tools cannot exceed what the operator\nsigned in at the provider is already permitted to do.\n\n## Two ways the surface fails silently\n\n- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is\n absent even with the flag enabled, and nothing reports why. `mkcert` covers local\n development.\n- **The dashboard embeds `ui/dist` into its binary.** Rebuilding the distribution is\n not deploying it: a running process can serve a bundle without tools while the\n built one has them, or serve a bundle older than its own binary.\n" + }, { "url": "/dev/architecture/dependencies-and-contracts/", "title": "Dependencies and Contracts", @@ -46,7 +52,7 @@ "url": "/dev/architecture/identity/", "title": "Identity", "section": "Architecture", - "body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## System identity\n\nArchie has exactly one built-in system identity. It is created during initial\nstore bootstrap, is strictly always active, and cannot be suspended or retired.\nIts `IdentityID` and kind are immutable.\n\nStartup, migration, supervision, remediation, and rollback actions performed by\nthe application use the system identity. The system identity MUST NOT be\ndelegated to individual identities. Every user, bot, service account, or other\nactor mutation records the identity that actually performed it.\n\nSystem capabilities may independently become unhealthy or unavailable without\nchanging the system identity.\n\n## Target placement and contracts\n\nThe Identity domain lives at `internal/domain/identity`.\n\nIt owns:\n\n- `IdentityID`, identity kind, display name, lifecycle, version, and audit\n timestamps;\n- create, rename, suspend, reactivate, and retire commands;\n- corresponding lifecycle events;\n- the repository contract required for durable identity records;\n- lookup of current and historical identities.\n\nExternal account bindings and capability settings remain with the domains that\nuse them and reference `IdentityID`.\n\n## Migration constraints\n\nMigration from the current string model MUST:\n\n- bootstrap the permanent system identity;\n- assign stable IDs to configured identities without losing their names;\n- replace empty-string legacy ownership with the system identity;\n- migrate tasks and sessions to canonical identity references;\n- include identity where task uniqueness and transport deduplication require\n independent ownership;\n- route container RPC through the task owner's capability bindings;\n- retain historical resolution after rename, suspension, or retirement;\n- remove identity-string equality from authentication or access semantics.\n\nThis completes the foundation required to restructure the current Identity\nbehaviour. Exact storage schemas and Go method signatures belong to\nimplementation design, not this architecture review.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## Explicit non-responsibilities\n\nIdentity is not authentication and is not access control.\n\nThe current architecture does not require authentication or authorization. Those\ncapabilities MAY be introduced later if deployment or product needs justify\nthem. They MUST remain separate from the identity model.\n\nAn identity reference therefore proves attribution within Archie's trusted\nsystem model; it does not by itself prove credentials or permission.\n\n## Per-identity configuration\n\nValues selected for an identity remain external configuration values. At\ncomposition time they are split into the runtime settings owned by the affected\ndomains and correlated by identity reference.\n\nThe existing `IdentityConfig` aggregate MUST be dissolved. Forge accounts,\nrepositories, models, providers, workspace behaviour, polling, budgets,\nnotifications, and transport namespaces retain their respective owners.\n\n## Audit\n\nConfiguration changes and other state changes are actions attributed to an\nidentity. System-initiated changes use the system identity. Their audit records\nMUST preserve the acting identity, the target, and the resulting change.\n\nThe command ownership and persistence mechanism for configuration changes is a\nseparate configuration-management decision.\n\n## Current implementation\n\nIdentity is not currently implemented as a domain. It is a collection of string\nfields and process-local associations:\n\n- `config.IdentityConfig.Name` is the daemon routing key.\n- `config.IdentityConfig.BotUser` is the external forge and Git author name.\n- `daemon.IdentityRunner` bundles the configured name with a forge client,\n worktree manager, repository list, configuration subset, logger, and polling\n goroutine.\n- `store.Task.Identity` persists the configured name on tasks.\n- NATS task messages copy the same configured name.\n- gateway routing accepts an identity name and uses it to select a repository\n profile.\n- gateway sessions persist `BotUser`, not the configured identity name.\n\nThere is no identity registry, identity record, identity lifecycle state,\nidentity persistence, or identity command/event model. Removing an identity from\nconfiguration makes existing task ownership unresolvable.\n\nAn empty identity string selects the legacy single-identity path. This gives the\nempty string behavioural meaning rather than representing a real system\nidentity.\n\n## Current enforcement and isolation\n\nThe current implementation uses identity equality as an authorization check for\nchat task approval and cancellation. This conflicts with the approved rule that\nidentity is attribution rather than authentication or access control and must be\nreassigned to an appropriate task-ownership or future access policy.\n\nFocused tests verify that:\n\n- a task resolves the forge client and repository list associated with its\n configured identity name;\n- cross-identity repository profiles do not leak;\n- chat task creation propagates the selected identity;\n- task persistence retains the identity string;\n- chat task control rejects a different identity string.\n\n## Current hazards\n\n- SQLite task uniqueness is `(owner, repo, issue_number)` and excludes identity.\n Two identities discovering the same forge issue cannot own distinct task\n records.\n- NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery\n by a second identity can be discarded as a duplicate.\n- Container-mode forge and worktree RPC servers are wired to the root clients,\n not the task owner's clients. The source documents this as an unresolved\n identity leak.\n- The shared task queue claims the oldest task without identity partitioning and\n relies on later string lookup to recover the correct runner.\n- Sessions use forge bot usernames where tasks use configured identity names, so\n there is no canonical cross-domain identity reference.\n- Identity lifecycle is process lifetime only; there is no disabled, degraded,\n retired, or unavailable state and no audit history.\n\nThe focused identity tests pass. Broader daemon and NATS suites could not open\nembedded listener ports in the current sandbox; their failures occurred before\nidentity behaviour executed.\n\n## Three-layer identity model\n\nAgreed 2026-07-30; the frame for SOUL\n([#68](https://github.com/samcharles93/archie-core/issues/68)) and the curator\n([#435](https://github.com/samcharles93/archie-core/issues/435)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Layer 1 — invariants.** Instruction precedence, core rules, and the `\u003ctools\u003e`\nand `\u003cenv\u003e` blocks live in `internal/gateway/templates/archie.md.tpl` and are\nunreachable at runtime by anyone.\n\n**Layer 2 — SOUL.** User-authored identity: agent name, register, warmth.\nEditable without a rebuild.\n\n**Enforcing the Layer 1 / Layer 2 boundary.** SOUL is rendered as the\n`Persona` field of `SystemPromptConfig` (`internal/gateway/prompt.go`) into a\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block, XML-escaped through\nthe same `xml` template helper used for tool and env metadata, and placed\n*before* `\u003cinstruction_precedence\u003e` in `archie.md.tpl`. Escaping means SOUL\ntext can never forge a live `\u003ccore_rules\u003e`, `\u003cinstruction_precedence\u003e`,\n`\u003ctools\u003e` or `\u003cenv\u003e` tag -- an attempt renders as inert escaped text\n(`\u0026lt;core_rules\u0026gt;...`), and `\u003cinstruction_precedence\u003e` explicitly tells the\nmodel the `\u003csoul\u003e` block is reference data, not an authority. This is\nguarded by `TestBuildSystemPromptSoulCannotOverrideInvariants` in\n`internal/gateway/prompt_test.go`, which renders a hostile SOUL that attempts\nto countermand `core_rules` and asserts the real invariant tags stay singular\nand their text stays intact. Keep this test in sync if the template's escaping\nor block structure changes -- do not relax it to make a future SOUL feature\n(e.g. curator-proposed edits) fit.\n\n**Layer 3 — representation.** Curator-derived knowledge about the user. It may\nonly **propose** changes to SOUL and never apply them. If derived conclusions can\nsilently rewrite tone, personality drifts and the user loses the control SOUL\nexists to give them. A proposal queue also makes the visibility requirement fall\nout for free, since pending conclusions are inherently reviewable.\n\n**Why SOUL comes first:** tone currently lives in Go string constants\n(`DefaultPersonas` in `internal/gateway/persona.go`), so fixing a rude reply on\n2026-07-29 required editing Go and rebuilding. SOUL is small, fixes a real\ndefect, and defines the boundary the curator must respect.\n" + "body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## System identity\n\nArchie has exactly one built-in system identity. It is created during initial\nstore bootstrap, is strictly always active, and cannot be suspended or retired.\nIts `IdentityID` and kind are immutable.\n\nStartup, migration, supervision, remediation, and rollback actions performed by\nthe application use the system identity. The system identity MUST NOT be\ndelegated to individual identities. Every user, bot, service account, or other\nactor mutation records the identity that actually performed it.\n\nSystem capabilities may independently become unhealthy or unavailable without\nchanging the system identity.\n\n## Target placement and contracts\n\nThe Identity domain lives at `internal/domain/identity`.\n\nIt owns:\n\n- `IdentityID`, identity kind, display name, lifecycle, version, and audit\n timestamps;\n- create, rename, suspend, reactivate, and retire commands;\n- corresponding lifecycle events;\n- the repository contract required for durable identity records;\n- lookup of current and historical identities.\n\nExternal account bindings and capability settings remain with the domains that\nuse them and reference `IdentityID`.\n\n## Migration constraints\n\nMigration from the current string model MUST:\n\n- bootstrap the permanent system identity;\n- assign stable IDs to configured identities without losing their names;\n- replace empty-string legacy ownership with the system identity;\n- migrate tasks and sessions to canonical identity references;\n- include identity where task uniqueness and transport deduplication require\n independent ownership;\n- route container RPC through the task owner's capability bindings;\n- retain historical resolution after rename, suspension, or retirement;\n- remove identity-string equality from authentication or access semantics.\n\nThis completes the foundation required to restructure the current Identity\nbehaviour. Exact storage schemas and Go method signatures belong to\nimplementation design, not this architecture review.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## Explicit non-responsibilities\n\nIdentity is not authentication and is not access control.\n\nThe current architecture does not require authentication or authorization. Those\ncapabilities MAY be introduced later if deployment or product needs justify\nthem. They MUST remain separate from the identity model.\n\nAn identity reference therefore proves attribution within Archie's trusted\nsystem model; it does not by itself prove credentials or permission.\n\n## Per-identity configuration\n\nValues selected for an identity remain external configuration values. At\ncomposition time they are split into the runtime settings owned by the affected\ndomains and correlated by identity reference.\n\nThe existing `IdentityConfig` aggregate MUST be dissolved. Forge accounts,\nrepositories, models, providers, workspace behaviour, polling, budgets,\nnotifications, and transport namespaces retain their respective owners.\n\n## Audit\n\nConfiguration changes and other state changes are actions attributed to an\nidentity. System-initiated changes use the system identity. Their audit records\nMUST preserve the acting identity, the target, and the resulting change.\n\nThe command ownership and persistence mechanism for configuration changes is a\nseparate configuration-management decision.\n\n## Current implementation\n\nIdentity is not currently implemented as a domain. It is a collection of string\nfields and process-local associations:\n\n- `config.IdentityConfig.Name` is the daemon routing key.\n- `config.IdentityConfig.BotUser` is the external forge and Git author name.\n- `daemon.IdentityRunner` bundles the configured name with a forge client,\n worktree manager, repository list, configuration subset, logger, and polling\n goroutine.\n- `store.Task.Identity` persists the configured name on tasks.\n- NATS task messages copy the same configured name.\n- gateway routing accepts an identity name and uses it to select a repository\n profile.\n- gateway sessions persist `BotUser`, not the configured identity name.\n\nThere is no identity registry, identity record, identity lifecycle state,\nidentity persistence, or identity command/event model. Removing an identity from\nconfiguration makes existing task ownership unresolvable.\n\nAn empty identity string selects the legacy single-identity path. This gives the\nempty string behavioural meaning rather than representing a real system\nidentity.\n\n## Current enforcement and isolation\n\n## Withheld judgement verbs\n\n`approve`, `reject`, `abandon` and `archive` are not exposed to an agent. An agent\nthat can approve can approve its own work, and the one control this surface exists\nto keep is a human accepting it.\n\nThe constraint is attribution, not capability: a task action records the acting\nidentity and the authorising principal, so exposing the verbs requires that an\nagent's action be recorded as an agent's and the authority it used recorded\nseparately. Until a surface carries both, the verbs stay withheld. This is the\nreason the four verbs are absent from the dashboard's in-browser tools, and it is\nwhy releasing them is a change to this boundary rather than a change to the tools.\n\n\nThe current implementation uses identity equality as an authorization check for\nchat task approval and cancellation. This conflicts with the approved rule that\nidentity is attribution rather than authentication or access control and must be\nreassigned to an appropriate task-ownership or future access policy.\n\nFocused tests verify that:\n\n- a task resolves the forge client and repository list associated with its\n configured identity name;\n- cross-identity repository profiles do not leak;\n- chat task creation propagates the selected identity;\n- task persistence retains the identity string;\n- chat task control rejects a different identity string.\n\n## Current hazards\n\n- SQLite task uniqueness is `(owner, repo, issue_number)` and excludes identity.\n Two identities discovering the same forge issue cannot own distinct task\n records.\n- NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery\n by a second identity can be discarded as a duplicate.\n- Container-mode forge and worktree RPC servers are wired to the root clients,\n not the task owner's clients. The source documents this as an unresolved\n identity leak.\n- The shared task queue claims the oldest task without identity partitioning and\n relies on later string lookup to recover the correct runner.\n- Sessions use forge bot usernames where tasks use configured identity names, so\n there is no canonical cross-domain identity reference.\n- Identity lifecycle is process lifetime only; there is no disabled, degraded,\n retired, or unavailable state and no audit history.\n\nThe focused identity tests pass. Broader daemon and NATS suites could not open\nembedded listener ports in the current sandbox; their failures occurred before\nidentity behaviour executed.\n\n## Three-layer identity model\n\nAgreed 2026-07-30; the frame for SOUL\n([#68](https://github.com/samcharles93/archie-core/issues/68)) and the curator\n([#435](https://github.com/samcharles93/archie-core/issues/435)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Layer 1 — invariants.** Instruction precedence, core rules, and the `\u003ctools\u003e`\nand `\u003cenv\u003e` blocks live in `internal/gateway/templates/archie.md.tpl` and are\nunreachable at runtime by anyone.\n\n**Layer 2 — SOUL.** User-authored identity: agent name, register, warmth.\nEditable without a rebuild.\n\n**Enforcing the Layer 1 / Layer 2 boundary.** SOUL is rendered as the\n`Persona` field of `SystemPromptConfig` (`internal/gateway/prompt.go`) into a\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block, XML-escaped through\nthe same `xml` template helper used for tool and env metadata, and placed\n*before* `\u003cinstruction_precedence\u003e` in `archie.md.tpl`. Escaping means SOUL\ntext can never forge a live `\u003ccore_rules\u003e`, `\u003cinstruction_precedence\u003e`,\n`\u003ctools\u003e` or `\u003cenv\u003e` tag -- an attempt renders as inert escaped text\n(`\u0026lt;core_rules\u0026gt;...`), and `\u003cinstruction_precedence\u003e` explicitly tells the\nmodel the `\u003csoul\u003e` block is reference data, not an authority. This is\nguarded by `TestBuildSystemPromptSoulCannotOverrideInvariants` in\n`internal/gateway/prompt_test.go`, which renders a hostile SOUL that attempts\nto countermand `core_rules` and asserts the real invariant tags stay singular\nand their text stays intact. Keep this test in sync if the template's escaping\nor block structure changes -- do not relax it to make a future SOUL feature\n(e.g. curator-proposed edits) fit.\n\n**Layer 3 — representation.** Curator-derived knowledge about the user. It may\nonly **propose** changes to SOUL and never apply them. If derived conclusions can\nsilently rewrite tone, personality drifts and the user loses the control SOUL\nexists to give them. A proposal queue also makes the visibility requirement fall\nout for free, since pending conclusions are inherently reviewable.\n\n**Why SOUL comes first:** tone currently lives in Go string constants\n(`DefaultPersonas` in `internal/gateway/persona.go`), so fixing a rude reply on\n2026-07-29 required editing Go and rebuilding. SOUL is small, fixes a real\ndefect, and defines the boundary the curator must respect.\n" }, { "url": "/dev/architecture/messaging-and-work-intake/", @@ -436,6 +442,10 @@ "title": "Configuration", "url": "/dev/architecture/configuration/" }, + { + "title": "The dashboard's tools for an in-browser agent", + "url": "/dev/architecture/dashboard-agent-tools/" + }, { "title": "Dependencies and Contracts", "url": "/dev/architecture/dependencies-and-contracts/" diff --git a/docs/news/archied/1.35.0.md b/docs/news/archied/1.35.0.md index a91c2d41f..fc145c0f7 100644 --- a/docs/news/archied/1.35.0.md +++ b/docs/news/archied/1.35.0.md @@ -9,10 +9,6 @@ Released 2026-09-22. [All news](../index.md) `internal/app/controlplane`; the client half now lives in `internal/infrastructure/controlplanerpc`, and the app package keeps the server, the registry, the seeds, the validators and the schema derivation. -- **The PRD's guard now exists, and passes:** `cmd/archie-messaging/architecture_test.go` measures the - linked binary against the banned list, with `internal/domain/workflow/task` as an exception checked - in both directions. Before this the guard had never been written -- because it failed. A messaging - process linking a SQLite driver and the workflow engine is a severance hole, not a design choice. - The resource documents are type-aliased back into the app package, so there is one definition read under two names rather than a copy per side. @@ -20,8 +16,7 @@ Released 2026-09-22. [All news](../index.md) - The Messaging Service reports each channel's state, recorded **per channel**: one channel's failure marks only itself, a channel that cannot start is marked failed **with its reason** rather than only - logged, and one that returns is marked stopped. `internal/channels/status.Manager` finally has a - production writer. + logged, and one that returns is marked stopped. `internal/channels/status.Manager` reports each channel's state. - `PutChannelStatus`/`ListChannelStatus` carry that to the dashboard, following the config-snapshot split. The store **replaces the reported set**, so a channel the reporter stops mentioning is deleted rather than left as a stale `running`; an empty report clears the table, because hosting no diff --git a/docs/news/archied/1.36.0.md b/docs/news/archied/1.36.0.md index 7b086e992..f1cf3650b 100644 --- a/docs/news/archied/1.36.0.md +++ b/docs/news/archied/1.36.0.md @@ -14,29 +14,6 @@ Released 2026-09-22. [All news](../index.md) agent's call and a page script's call reach the server identically. Tools therefore record the signed-in identity and a source, and **never** that an agent acted. -### The four judgement verbs are deliberately absent - -- `approve`, `reject`, `abandon` and `archive` are **not** exposed. `internal/domain/taskactions` - records only a source string and stamps `KindHumanApproved`, so an agent's approval would be written - down as a person's. An agent that can approve can approve its own work, and the one control this - design exists to keep is a human accepting it. Those verbs land once task actions carry both the - acting identity and the authorising principal. - -### `consequentialHint` does not gate anything, and the release says so - -- Chrome 152 accepts `consequentialHint` at registration and **omits it from `getTools()`**, so no - client sees it and the browser cannot enforce what it does not surface. The three recovery tools - instead require an explicit `confirm: true`, which is a **deliberate-action signal rather than a - security control** an agent can trivially satisfy. The boundary that holds is the session: the tools - cannot exceed what the signed-in operator can already do. - -### Two ways this fails silently, now recorded next to the code - -- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is absent *even - with the flag*, and nothing reports why. `mkcert` covers local development. -- **`archie-ui` embeds `ui/dist` into its binary**, so rebuilding the distribution is not deploying it; - a running process can serve a bundle with no tools while the built one has them. - ### Binaries built by the development build task can be updated - `task build` passed the `installtype` stamp for three of six commands, so `archie-messaging`, diff --git a/docs/news/releases.json b/docs/news/releases.json index 734504a65..e25bbd470 100644 --- a/docs/news/releases.json +++ b/docs/news/releases.json @@ -11,14 +11,14 @@ "name": "archied", "version": "1.36.0", "date": "2026-09-22", - "body": "### The dashboard declares tools an in-browser agent can call\n\n- The dashboard registers **seven WebMCP tools**. Read-only: `list_tasks`, `get_task`,\n `recent_events`, `daemon_health`. Recovery: `retry_task`, `stop_task`, `cancel_task`. An agent\n operating the dashboard now reads structured state and recovers stuck work instead of scraping the\n UI.\n- Every tool wraps the same `ui/src/lib/api.ts` client the dashboard itself calls, so an agent and a\n person exercise one path rather than two.\n- `archie-ui` cannot be attributed to the agent that called it: a page can invoke its own tools, so an\n agent's call and a page script's call reach the server identically. Tools therefore record the\n signed-in identity and a source, and **never** that an agent acted.\n\n### The four judgement verbs are deliberately absent\n\n- `approve`, `reject`, `abandon` and `archive` are **not** exposed. `internal/domain/taskactions`\n records only a source string and stamps `KindHumanApproved`, so an agent's approval would be written\n down as a person's. An agent that can approve can approve its own work, and the one control this\n design exists to keep is a human accepting it. Those verbs land once task actions carry both the\n acting identity and the authorising principal.\n\n### `consequentialHint` does not gate anything, and the release says so\n\n- Chrome 152 accepts `consequentialHint` at registration and **omits it from `getTools()`**, so no\n client sees it and the browser cannot enforce what it does not surface. The three recovery tools\n instead require an explicit `confirm: true`, which is a **deliberate-action signal rather than a\n security control** an agent can trivially satisfy. The boundary that holds is the session: the tools\n cannot exceed what the signed-in operator can already do.\n\n### Two ways this fails silently, now recorded next to the code\n\n- **A secure context is required.** On a plain-HTTP origin `document.modelContext` is absent *even\n with the flag*, and nothing reports why. `mkcert` covers local development.\n- **`archie-ui` embeds `ui/dist` into its binary**, so rebuilding the distribution is not deploying it;\n a running process can serve a bundle with no tools while the built one has them.\n\n### Binaries built by the development build task can be updated\n\n- `task build` passed the `installtype` stamp for three of six commands, so `archie-messaging`,\n `archie-state-store` and `archie-ui` were built without it. An unstamped binary reports `unknown`\n and the self-update path **refuses rather than guesses**, which is how an operator ends up unable to\n update with `install type is unknown` and no way forward. All six are stamped now, and a test reads\n the build task and fails naming any command line that omits it." + "body": "### The dashboard declares tools an in-browser agent can call\n\n- The dashboard registers **seven WebMCP tools**. Read-only: `list_tasks`, `get_task`,\n `recent_events`, `daemon_health`. Recovery: `retry_task`, `stop_task`, `cancel_task`. An agent\n operating the dashboard now reads structured state and recovers stuck work instead of scraping the\n UI.\n- Every tool wraps the same `ui/src/lib/api.ts` client the dashboard itself calls, so an agent and a\n person exercise one path rather than two.\n- `archie-ui` cannot be attributed to the agent that called it: a page can invoke its own tools, so an\n agent's call and a page script's call reach the server identically. Tools therefore record the\n signed-in identity and a source, and **never** that an agent acted.\n\n### Binaries built by the development build task can be updated\n\n- `task build` passed the `installtype` stamp for three of six commands, so `archie-messaging`,\n `archie-state-store` and `archie-ui` were built without it. An unstamped binary reports `unknown`\n and the self-update path **refuses rather than guesses**, which is how an operator ends up unable to\n update with `install type is unknown` and no way forward. All six are stamped now, and a test reads\n the build task and fails naming any command line that omits it." }, { "component": "archied", "name": "archied", "version": "1.35.0", "date": "2026-09-22", - "body": "### The Messaging Service is severed from the store and workflow runtime\n\n- `cmd/archie-messaging` no longer links `modernc.org/sqlite`, `internal/store`,\n `internal/domain/workflow` or `internal/agentexec`. All four arrived through a single import of\n `internal/app/controlplane`; the client half now lives in\n `internal/infrastructure/controlplanerpc`, and the app package keeps the server, the registry, the\n seeds, the validators and the schema derivation.\n- **The PRD's guard now exists, and passes:** `cmd/archie-messaging/architecture_test.go` measures the\n linked binary against the banned list, with `internal/domain/workflow/task` as an exception checked\n in both directions. Before this the guard had never been written -- because it failed. A messaging\n process linking a SQLite driver and the workflow engine is a severance hole, not a design choice.\n- The resource documents are type-aliased back into the app package, so there is one definition read\n under two names rather than a copy per side.\n\n### Channel lifecycle reaches the dashboard\n\n- The Messaging Service reports each channel's state, recorded **per channel**: one channel's failure\n marks only itself, a channel that cannot start is marked failed **with its reason** rather than only\n logged, and one that returns is marked stopped. `internal/channels/status.Manager` finally has a\n production writer.\n- `PutChannelStatus`/`ListChannelStatus` carry that to the dashboard, following the config-snapshot\n split. The store **replaces the reported set**, so a channel the reporter stops mentioning is\n deleted rather than left as a stale `running`; an empty report clears the table, because hosting no\n channels is a fact worth reporting; and an id-less row is refused, since it could never be replaced\n or removed by a later report.\n- `Service.ReloadChannel` routes to the channel's own seam and refuses a channel that cannot reload\n with a reason rather than accepting and ignoring it. `ReloadSupported` was previously declared **by\n name**, so a channel could advertise reload with nothing behind it; one function now decides both.\n\n### Action playbooks: a second playbook shape, with typed results\n\n- A playbook is now one of two shapes: a **workflow playbook** (exactly one `workflow` action,\n unchanged) or an **action playbook** (one or more `module` actions in order). A playbook does not\n mix them.\n- `args` and `when` share one compilation path and one evaluation context, and `actions.` is typed\n by the kind that action runs, so a misspelled result field, an unknown id, a map index, `in`, a\n comprehension, or a shape-foreign key (`kind` on a `workflow` action, `workflow` on a `module`\n action) is a **load failure** rather than a dispatch failure.\n- **Action playbooks load but do not run yet.** Routing arrives with the first side-effecting\n position; the daemon warns at load rather than accepting them silently.\n- The CEL environment is built per playbook, because result typing depends on the ids a playbook\n declares.\n- `ModuleRegistry.DecodeResult` turns a kind's flat map result into its typed `Result` before a later\n expression reads it. Without it a typed read evaluated against a shape the run never produces, and\n so silently read null." + "body": "### The Messaging Service is severed from the store and workflow runtime\n\n- `cmd/archie-messaging` no longer links `modernc.org/sqlite`, `internal/store`,\n `internal/domain/workflow` or `internal/agentexec`. All four arrived through a single import of\n `internal/app/controlplane`; the client half now lives in\n `internal/infrastructure/controlplanerpc`, and the app package keeps the server, the registry, the\n seeds, the validators and the schema derivation.\n- The resource documents are type-aliased back into the app package, so there is one definition read\n under two names rather than a copy per side.\n\n### Channel lifecycle reaches the dashboard\n\n- The Messaging Service reports each channel's state, recorded **per channel**: one channel's failure\n marks only itself, a channel that cannot start is marked failed **with its reason** rather than only\n logged, and one that returns is marked stopped. `internal/channels/status.Manager` reports each channel's state.\n- `PutChannelStatus`/`ListChannelStatus` carry that to the dashboard, following the config-snapshot\n split. The store **replaces the reported set**, so a channel the reporter stops mentioning is\n deleted rather than left as a stale `running`; an empty report clears the table, because hosting no\n channels is a fact worth reporting; and an id-less row is refused, since it could never be replaced\n or removed by a later report.\n- `Service.ReloadChannel` routes to the channel's own seam and refuses a channel that cannot reload\n with a reason rather than accepting and ignoring it. `ReloadSupported` was previously declared **by\n name**, so a channel could advertise reload with nothing behind it; one function now decides both.\n\n### Action playbooks: a second playbook shape, with typed results\n\n- A playbook is now one of two shapes: a **workflow playbook** (exactly one `workflow` action,\n unchanged) or an **action playbook** (one or more `module` actions in order). A playbook does not\n mix them.\n- `args` and `when` share one compilation path and one evaluation context, and `actions.` is typed\n by the kind that action runs, so a misspelled result field, an unknown id, a map index, `in`, a\n comprehension, or a shape-foreign key (`kind` on a `workflow` action, `workflow` on a `module`\n action) is a **load failure** rather than a dispatch failure.\n- **Action playbooks load but do not run yet.** Routing arrives with the first side-effecting\n position; the daemon warns at load rather than accepting them silently.\n- The CEL environment is built per playbook, because result typing depends on the ids a playbook\n declares.\n- `ModuleRegistry.DecodeResult` turns a kind's flat map result into its typed `Result` before a later\n expression reads it. Without it a typed read evaluated against a shape the run never produces, and\n so silently read null." }, { "component": "archied",