@llblab/pi-telegram 0.35.2 → 0.36.1

package/docs/compact-matrix-literal.md

@@ -1,189 +1,176 @@
-# Compact Matrix Literal
+# Adaptive Button Literal
 
-> Status: Portable v1 standard implemented by the `pi-telegram` 0.35.0 release candidate.
+> Status: Portable CML v3 standard implemented by the unreleased `pi-telegram` control-surface parser.
 
-Compact Matrix Literal (CML) is a bounded-depth text format for ordered key-value cells arranged as singleton or compact rows. It optimizes repeated interactive controls where JSON field names, quotes, and commas dominate the payload.
+Adaptive Button Literal is one bounded-depth matrix grammar over a shared button AST. It accepts strict JSON button objects, positional Compact Matrix Literal (CML) cells, or both in the same matrix and row. Commas between completed matrix or row elements are optional, so producers can progressively compress representation without changing runtime meaning.
 
-CML is transport-neutral. An embedding maps each decoded cell's `key` and `value` to its own domain. The `pi-telegram` profile maps `key` to button label and `value` to button prompt.
-
-## Goals
+```text
+full named JSON → comma-optional adjacency → mixed named/positional cells → compact CML
+```
 
-- Encode common key-value matrices with minimal punctuation.
-- Preserve ordered singleton and compact rows.
-- Preserve non-structural Unicode text literally.
-- Admit deterministic linear-time parsing without evaluation or recovery.
-- Remain deterministic beside an existing JSON form.
-- Fail closed on malformed or deeper structures.
+The compact form is not JSON: `{label|prompt|variant}` assigns meaning by position. The formats share semantics and topology, not syntax.
 
-## Non-Goals
+## Goals
 
-- Replacing JSON for arbitrary objects, metadata, styles, or extensible schemas.
-- Defining callback ownership, application state, rendering policy, or transport behavior.
-- Recovering partial intent from malformed input.
-- Defining one universal visual row-width limit for every renderer.
+- Preserve one ordered button matrix across multiple representation densities.
+- Let producers compress individual cells without converting the whole surface.
+- Preserve valid strict JSON behavior unchanged.
+- Admit deterministic linear-time parsing without evaluation or partial recovery.
+- Keep rendering, callback ownership, and application state outside the notation.
 
 ## Data Model
 
-A decoded payload is an ordered non-empty list of non-empty rows:
+Every accepted payload normalizes to a non-empty ordered list of non-empty rows:
 
 ```text
-Cell = { key: string, value: string }
+Cell = { label?: string, prompt?: string, value?: string, selected_style?: string }
 Rows = Cell[][]
 ```
 
-A top-level cell normalizes to a singleton row. A nested row preserves its compact grouping.
+A top-level cell becomes a singleton row. A nested row preserves horizontal grouping.
 
-A cell with one atom copies its key into its value:
+These representations are semantically equivalent:
 
 ```text
-{7} == { key: "7", value: "7" }
+[[{"label":"Pause","prompt":"music::pause"},{"value":"Next"}],{"value":"Status"}]
+[[{"label":"Pause","prompt":"music::pause"}{"value":"Next"}]{"value":"Status"}]
+[[{"label":"Pause","prompt":"music::pause"},{Next}],{Status}]
+[[{Pause|music::pause}{Next}]{Status}]
 ```
 
-A cell with two atoms separates key and value with one unescaped vertical bar:
+Named JSON objects and positional cells may coexist within the same horizontal row:
 
 ```text
-{🟥|2,5} == { key: "🟥", value: "2,5" }
+[[{"label":"Open","prompt":"/tmp"}{Back|/}]]
 ```
 
-## Grammar
+## Positional Cells
 
-The normative structural grammar is:
+A one-atom cell copies its value into label and prompt through the existing button contract:
 
 ```text
-payload  := cell | matrix
-matrix   := "[" ws element (ws element)* ws "]"
-element  := cell | row
-row      := "[" ws cell (ws cell)* ws "]"
-cell     := "{" atom "}"
-          | "{" atom "|" atom "}"
-atom     := atom-unit+
-atom-unit := ordinary | "\\|" | "\\}" | "\\\\"
-ws       := *(SP | HTAB | CR | LF)
+{Next}
 ```
 
-`ordinary` is any printable Unicode scalar other than unescaped `|`, unescaped `}`, or `\`. No commas separate elements. A matrix and every nested row must contain at least one element. A row cannot contain another row.
-
-Examples:
+A two-atom cell separates label and prompt:
 
 ```text
-{Continue}
-{Open|/tmp}
-[{Up|/}[{Prev|page-1}{Next|page-3}]{etc|/etc}]
-[[{1}{2}{3}{4}{5}{6}{7}{8}]]
-{A \| B|C:\\Games\}}
+{Pause|music::pause}
 ```
 
-These normalize respectively to one copied singleton cell, one key-value singleton cell, a mixed singleton/compact matrix, one eight-cell row, and `{ key: "A | B", value: "C:\\Games}" }`.
-
-## Atoms, Whitespace, And Escapes
-
-Leading and trailing whitespace in each decoded key and value is trimmed. Internal ordinary spaces are preserved. CR, LF, HTAB, C0 controls, DEL, and C1 controls that remain inside an atom after trimming are invalid.
-
-Only three escape sequences exist:
+A three-atom cell adds the selected style:
 
 ```text
-\|  → literal |
-\}  → literal }
-\\  → literal \
+{Stop|music::stop|danger}
 ```
 
-Unknown escapes and a trailing backslash are invalid. No character is silently dropped.
+The style atom is accepted only as `primary`, `success`, or `danger`.
 
-Every other printable character is literal inside a cell, including:
+## Adaptive Grammar
+
+The structural grammar is:
 
 ```text
-{ [ ] " : , / emoji and ordinary spaces
+payload         := json-object | matrix | positional-cell
+matrix          := "[" ws element (boundary element)* ws "]"
+element         := cell | row
+row             := "[" ws cell (boundary cell)* ws "]"
+cell            := json-object | positional-cell
+boundary        := ws [","] ws
+positional-cell := "{" atom "}"
+                 | "{" atom "|" atom "}"
+                 | "{" atom "|" atom "|" atom "}"
+atom            := atom-unit+
+atom-unit       := ordinary | "\|" | "\}" | "\\"
+ws              := *(SP | HTAB | CR | LF)
 ```
 
-An opening `{` has no structural meaning after a cell has begun. Square brackets are structural only outside a cell. A second unescaped vertical bar is invalid. When multiline text or additional metadata is needed, the producer uses the embedding's JSON or other full-fidelity form.
+`boundary` occurs only after one complete element and before another. It may contain one comma or no comma. Element delimiters make empty adjacency unambiguous. Leading, repeated, and trailing commas are invalid.
 
-## Width Policy
+A `json-object` is one complete strict JSON object. Its property commas, strings, escaping, nested values, and other internals remain ordinary strict JSON; comma optionality applies only between matrix or row elements.
 
-CML Core does not impose a visual row-width maximum. Width is a renderer and interaction-policy concern, not a property of the key-value matrix wire format.
+Rows cannot contain rows. The grammar never recurses beyond one row inside the top-level matrix.
 
-An embedding may enforce a documented host limit. The `pi-telegram` parser does not add an artificial per-row width cap because Telegram Bot API does not document one and existing top-level matrices already admit host-bounded action counts. Its bundled Generated Control Surface Skill owns UX policy: five columns are the proven default for short position-bearing labels, six to eight may be used only when labels remain compact and readable, and wider surfaces should normally be regrouped.
+## Atoms, Whitespace, And Escapes
 
-## Parsing Contract
+Leading and trailing whitespace in positional atoms is trimmed. Internal ordinary spaces are preserved. CR, LF, HTAB, C0 controls, DEL, and C1 controls remaining inside an atom after trimming are invalid.
 
-A conforming parser:
+Only three positional-cell escapes exist:
 
-1. Consumes Unicode text without executing, interpolating, or evaluating it.
-2. Parses exactly one `payload` and rejects trailing non-whitespace input.
-3. Rejects empty atoms, empty matrices, empty rows, and nesting deeper than one row inside the top-level matrix.
-4. Rejects missing, extra, crossed, or mismatched delimiters.
-5. Rejects a second unescaped vertical bar in a cell.
-6. Decodes only `\|`, `\}`, and `\\`; unknown or trailing escapes fail.
-7. Trims atom boundaries, then rejects empty values and remaining control characters.
-8. Returns no partial rows or cells after any failure.
-9. Runs in linear time over a host-bounded payload and does not recurse beyond the fixed grammar depth.
+```text
+\|  → literal |
+\}  → literal }
+\\  → literal \
+```
 
-Implementations may report diagnostics internally, but an invalid payload must not register or execute any action.
+Every other printable character is literal inside a positional cell, including commas, colons, quotes, square brackets, emoji, and ordinary spaces. A comma inside `{label|prompt}` is data; a comma after the closing `}` is an optional element separator.
 
-## JSON Coexistence
+## Deterministic Parsing
 
-An embedding that already accepts JSON uses deterministic routing:
+A conforming parser:
 
-1. Attempt strict JSON parsing first for payloads beginning with `{` or `[`.
-2. If JSON parsing succeeds, validate only against the embedding's JSON schema. A JSON shape failure must not fall back to CML.
-3. If JSON parsing fails, attempt CML from the original source.
-4. Accept CML only after complete grammar and embedding validation.
+1. Attempts strict JSON first for sources beginning with `{` or `[`. Successful JSON is validated only against the existing button matrix schema and never reinterpreted.
+2. If strict JSON parsing fails, parses the original source with the adaptive grammar.
+3. Tries one complete strict JSON object at each cell boundary before positional interpretation.
+4. Accepts at most one optional comma between completed matrix or row elements.
+5. Rejects leading, repeated, trailing, or property-level omitted commas.
+6. Rejects empty atoms, matrices, rows, and nesting deeper than one row.
+7. Decodes only `\|`, `\}`, and `\\` in positional cells.
+8. Consumes exactly one complete payload and rejects trailing content.
+9. Returns no partial rows or cells after any failure.
+10. Runs in linear time over a host-bounded payload with fixed grammar depth.
 
-Valid JSON behavior therefore remains unchanged. A malformed JSON-looking source receives no tolerant recovery: it is accepted only when it independently forms a complete valid CML payload.
+Malformed JSON-looking input receives no generic recovery. It is accepted only if it independently forms a complete valid adaptive literal.
 
-## `pi-telegram` Profile
+## Telegram Profile
 
-For `telegram_button` and its exact `telegram_buttons` alias:
+For `telegram_button` and the exact `telegram_buttons` alias:
 
-- `Cell.key` becomes the visible button label.
-- `Cell.value` becomes the queued prompt.
-- A top-level cell becomes one full-width inline-keyboard row.
-- A nested row becomes one horizontal row.
-- `{value}` is equivalent to JSON `{"value":"value"}`.
-- `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
-- JSON and double-quoted attributes remain the full-fidelity forms.
-- `selected_style` and future metadata are not represented by CML v1.
-- Invalid CML is stripped with its enclosing recognized action comment and registers no callbacks, matching existing fail-closed action behavior.
+- JSON `value` keeps its existing label/prompt fallback semantics.
+- Positional `{value}` is equivalent to JSON `{"value":"value"}`.
+- Positional `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
+- Positional `{label|prompt|selected_style}` is equivalent to the corresponding three-field JSON object.
+- Top-level cells become full-width rows.
+- Nested rows become horizontal keyboard rows.
+- Invalid payloads are stripped with their recognized action comment and register no callbacks.
 
-Example embedding:
+Example:
 
 ```html
-<!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
+<!-- telegram_button [{⬆️ Up|/},[{⬅️|page-1}{➡️|page-3}],{"label":"📁 etc","prompt":"/etc"}] -->
 ```
 
-The enclosing HTML-comment transport still owns its own delimiter boundary; content containing the comment terminator cannot reach the CML parser and must use another supported delivery representation.
+The enclosing HTML-comment transport owns its own delimiter boundary. Content containing the comment terminator must use another supported representation.
 
-## Conformance Classes
+## Width Policy
+
+The grammar imposes no visual row-width maximum. Renderer and interaction policy own width. The bundled Generated Control Surface Skill defaults to at most five short position-bearing controls per row, permits six to eight only when labels remain compact, and treats eight as the phone-width UX maximum.
 
-A conformance suite covers properties rather than incident-specific strings.
+## Conformance
 
-### Accepted
+Accepted classes include:
 
-- Singular copied and key-value cells.
-- Top-level singleton rows.
-- Nested rows at widths one, five, and eight.
-- Mixed singleton and compact rows.
-- Unicode, punctuation, brackets, quotes, commas, colons, and internal spaces.
-- Trimmed atom boundaries.
-- Each defined escape sequence.
-- Structural whitespace between tokens.
-- Semantic equivalence with supported JSON cell forms.
+- Strict JSON objects and matrices.
+- Positional singleton, two-atom, and styled cells.
+- Matrices and rows with commas, without commas, or a mixture of boundaries.
+- Named JSON and positional cells mixed in one matrix or row.
+- Literal commas inside positional atoms and strict JSON strings.
+- Unicode, defined escapes, structural whitespace, and rows at supported renderer widths.
+- Semantic equivalence across every progressive-compression step.
 
-### Rejected
+Rejected classes include:
 
-- Empty payload, matrix, row, key, or value.
-- Deeper nesting.
-- Missing or mismatched delimiters.
-- A second unescaped separator.
-- Unknown or trailing escapes.
-- Internal control characters.
-- Commas between cells.
-- Trailing garbage.
-- JSON that parses but fails the JSON action schema.
+- Empty payloads, matrices, rows, labels, prompts, or style atoms.
+- Leading, repeated, or trailing element commas.
+- Missing commas between properties inside a JSON object.
+- Deeper row nesting.
+- Missing, crossed, or mismatched delimiters.
+- A third positional separator, unknown style, unknown escape, or trailing backslash.
+- Internal control characters and trailing garbage.
+- Valid JSON that fails the existing JSON action schema.
 
 Every rejected case proves zero callback registration.
 
 ## Versioning
 
-This document defines CML v1. Compatible embeddings may impose documented host-level byte, cell-count, or width limits without changing the core grammar, but must preserve bounded-depth and fail-closed semantics.
-
-Future versions must not assign new meaning to input rejected by a security or ownership boundary without an explicit version discriminator. Metadata fields, styles, and deeper structures require a revised standard rather than permissive v1 parsing.
+This document defines CML v3. V3 extends the v2 positional grammar with strict JSON object cells, mixed representation, and optional element-boundary commas. It does not make JSON object internals permissive and does not add deeper structures. Future versions must preserve strict-JSON-first routing, bounded depth, atomic rejection, and an explicit discriminator for any new meaning at a security or ownership boundary.

package/docs/generative-apps.md

@@ -0,0 +1,310 @@
+# Generative Apps Runtime For Telegram
+
+_Status: incremental implementation. Canonical installation and explicit transactional replacement, agent-side method invocation, state/history commits, partial-tail recovery, cross-process transition locking with dead-owner recovery, installation-generation plus revision rejection for direct app-output controls, lifecycle-cancelled worker-isolated methods, the bounded non-shell process port, strict bound-action parsing, pre-model-queue `tgbtn` dispatch, new-message default views, and opt-in in-place bound-action edits with explicit-action send fallback are implemented locally. Agent-mediated initial-surface revision capture, process-birth lock proof, voice delivery, automatic refresh scheduling, removal, and complete lifecycle diagnostics remain open in the backlog._
+
+## Purpose
+
+This document specifies the concrete Generative App runtime implemented by `pi-telegram`. The transport-independent concept, vocabulary, application shapes, hybrid action model, and agent operating workflow belong to the bundled [`generative-apps` Skill](../skills/generative-apps/SKILL.md).
+
+The Telegram implementation provides managed installation, method execution, persistence, button binding, callback routing, and message delivery:
+
+```text
+Telegram control → bound method → state/capability owner
+Telegram view    ← rendered output ← fresh result
+```
+
+This runtime coexists with ordinary prompt buttons, companion-extension callbacks, Sections, and the Delivery API. It ships no application catalog or `examples/` tree; reusable domain scripts remain with their capability owners.
+
+## Ownership Split
+
+- The bundled [`generative-apps` Skill](../skills/generative-apps/SKILL.md) owns the general concept and agent operation: category definition, `generated` versus `generative`, application shapes, hybrid method/prompt surfaces, selection, authorship, review, workflow, safety, and validation judgment.
+- [`architecture.md`](./architecture.md#generative-apps) owns this runtime's place inside the Telegram bridge and its domain boundaries.
+- This document owns only `pi-telegram` implementation contracts: canonical managed identity, executable ABI, Telegram wire syntax, state timeline, installation/replacement, bounded ports, callback routing, delivery, lifecycle, and current limitations.
+- [`generated-control-surface`](../skills/generated-control-surface/SKILL.md) owns the separate ephemeral control-surface operating protocol.
+
+Keep conceptual guidance out of this document and Telegram runtime mechanics out of the Generative Apps Skill.
+
+## Canonical Layout And Identity
+
+Generative Apps live under the active Pi agent directory, never in package installation files or temporary storage:
+
+```text
+<agent-dir>/genapps/
+└── poker/
+    ├── poker.mjs
+    ├── state.json
+    └── states.jsonl
+```
+
+Identity is structural:
+
+```text
+app = directory name = module stem
+poker  = poker          = poker.mjs
+```
+
+No app manifest, per-app `package.json`, duplicated `name`, class registration, or default export is required. The `.mjs` extension supplies ESM semantics directly.
+
+An app name is a unique lowercase ASCII identifier accepted by the runtime's path-safe validation. It must not contain path separators, `..`, `::`, or a native callback namespace delimiter.
+
+## Inference-Bypass Syntax
+
+Compact Matrix Literal and full JSON buttons keep their existing `label + prompt` contract. A bound action is encoded entirely in the prompt string:
+
+```ebnf
+bound-action = app "::" method [ "(" json-value ")" ]
+```
+
+Examples:
+
+```text
+poker::fold
+poker::call(18)
+poker::init({"seed":"abc"})
+media::seek("+30s")
+```
+
+No argument means no decorative empty parentheses. One optional argument is a strict JSON value; the runtime never evaluates JavaScript source from the argument.
+
+CML:
+
+```text
+[{Fold|poker::fold}{Call 18|poker::call(18)}]
+```
+
+Equivalent JSON:
+
+```json
+[
+  [
+    { "label": "Fold", "prompt": "poker::fold" },
+    { "label": "Call 18", "prompt": "poker::call(18)" }
+  ]
+]
+```
+
+`app` is not a button property. Both representations normalize to the same prompt string, and routing happens afterward.
+
+The double colon is the inference-bypass operator: it routes a generated prompt control to a registered deterministic owner before Pi queue admission. Native extension callbacks retain their existing single-colon grammar:
+
+```text
+myext:action:payload   native callback_data namespace
+poker::call(18)        generated prompt routed to a Generative App
+```
+
+These routes do not conflict. Native callbacks are direct by construction. `::` exists only because an ordinary generated button prompt would otherwise enter the model queue.
+
+An absent, stale, or invalid bound app fails closed and never degrades into an accidental model prompt.
+
+## `telegram_bind` Tool
+
+One agent Tool owns installation and deliberate invocation through two mutually exclusive shapes.
+
+Install an external self-contained module and initialize it:
+
+```ts
+telegram_bind({
+  app: "poker",
+  script: "/path/to/poker.mjs",
+  argument: { seed: "abc" }
+})
+```
+
+The runtime copies the module to `<agent-dir>/genapps/poker/poker.mjs`, validates the canonical identity and required exports, transactionally invokes `init(argument)`, and initializes state. Existing installation is never overwritten without explicit replacement authority. Installed canonical modules are discovered directly when a bound action resolves; there is no separate app registry.
+
+Explicitly replace an installed app after editing its script:
+
+```ts
+telegram_bind({
+  app: "poker",
+  script: "/path/to/poker.mjs",
+  replace: true,
+  argument: { seed: "abc" }
+})
+```
+
+Replacement validates and initializes a complete staging app before publishing it under the existing app name. A failed `init` preserves the installed module, state, and timeline. Omitting `replace: true` keeps duplicate installation fail-closed, while setting it for an absent app also fails instead of silently changing replacement into installation.
+
+Discover or reuse an app already written at its canonical path and invoke a named method:
+
+```ts
+telegram_bind({
+  app: "poker",
+  method: "init",
+  argument: { seed: "abc" }
+})
+```
+
+Agent-side diagnostic invocation uses the same shape:
+
+```ts
+telegram_bind({ app: "poker", method: "inspect" })
+```
+
+`script` and `method` are mutually exclusive, and `replace` is valid only with `script`. Script installation or replacement implicitly invokes mandatory `init`; existing-app invocation names its method explicitly. Folder presence supplies durable discoverability across runtime replacement without introducing a manifest.
+
+During an active Telegram turn, `telegram_bind` displays successful app output directly through the current outbound planner and exact turn target by default, including initial `init` output; its Tool result tells the agent not to repeat or reformat the delivered view. Set `display: false` for agent-only diagnosis. Outside an active Telegram turn, the Tool returns bounded output for exact caller-owned presentation rather than choosing a Telegram target implicitly. The same method invoked through `app::method(argument)` routes its rendered output directly to the owning Telegram surface.
+
+## Module Contract
+
+A Generative App exports plain named async or synchronous functions. `init` is mandatory. Classes and default exports are outside the contract.
+
+```js
+export async function init({ argument, run, signal }) {
+  const seed = argument?.seed ?? "default";
+  return {
+    state: { seed, turn: 0 },
+    output: "**Ready**\n\n<!-- telegram_button {Start|poker::start} -->"
+  };
+}
+
+export async function start({ state }) {
+  const nextState = { ...state, turn: state.turn + 1 };
+  return {
+    state: nextState,
+    output: `**Turn:** \`${nextState.turn}\``
+  };
+}
+
+export async function inspect({ state }) {
+  return { output: JSON.stringify(state) };
+}
+```
+
+The runtime context may contain only bounded capabilities required by the contract:
+
+- Current immutable app state, absent for first initialization.
+- Parsed optional JSON argument.
+- Cancellation signal and current app revision.
+- A bounded non-shell process port for coherent CLI adapters.
+- Redacted app/target metadata needed for diagnostics and rendering ownership.
+
+The runtime does not pass a raw Telegram client, bot token, Pi extension context, arbitrary transport operation, or mutable queue/session state.
+
+A method result contains:
+
+```ts
+interface GenerativeAppResult {
+  state?: JsonValue;
+  output: string;
+  viewMode?: "new" | "edit";
+}
+```
+
+`output` is ordinary assistant Markdown plus existing top-level voice/button markup. It passes through the established outbound planner rather than defining a second rendering language. Omitted `viewMode` defaults to `"new"`: the result arrives as a fresh message and the clicked button remains visibly selected on its prior surface. `viewMode: "edit"` opts one result into replacing the callback message and keyboard in place when Telegram permits it; edit failure after that explicit action may fall back to one new message.
+
+Returning `state` requests a committed transition. Omitting `state` makes the method output-only, which supports inspection and live refresh without appending duplicate history. Invalid, oversized, non-serializable, or malformed results fail before state or Telegram effects commit.
+
+## Current State And State Timeline
+
+`state.json` is the compact current projection read by the runtime and, when useful, by the agent:
+
+```json
+{
+  "seed": "abc",
+  "turn": 2
+}
+```
+
+`states.jsonl` is the committed-state timeline. Its first line is the successful initial state; each later state-changing method appends one complete snapshot envelope:
+
+```jsonl
+{"revision":0,"method":"init","argument":{"seed":"abc"},"state":{"seed":"abc","turn":0}}
+{"revision":1,"method":"start","state":{"seed":"abc","turn":1}}
+{"revision":2,"method":"start","state":{"seed":"abc","turn":2}}
+```
+
+The state in `state.json` equals the state in the latest complete journal line. Runtime-owned locking, revision checks, complete-line append, atomic replacement, and recovery preserve that relation across concurrent clicks and interruption. A partial final JSONL line is never treated as committed state.
+
+A successful `init` is a hard new-run boundary. It transactionally clears current state and prior history, writes the new initial snapshot as revision zero, and publishes the initial output. Initialization failure preserves the previous working state and journal unchanged.
+
+Application state is the app's complete persistent checkpoint: it includes interaction/configuration state plus the latest normalized external projection needed to render, diagnose, or reconstruct the current view. An agent reading `state.json` should be able to identify material app reality such as selected track, playback state, queue position, backend, and last observation without executing the app first. This projection is explicitly a last-observed cache, not the external domain authority: before a mutation, explicit status, or refresh, a CLI-backed app re-reads the actual owner, then commits a new complete snapshot only when retained app state materially changes.
+
+## CLI Capability Adapters
+
+A Generative App may compose several existing CLI tools when they belong to one coherent domain or user journey:
+
+```text
+media Generative App → playerctl + mpv + local media library
+git Generative App   → git + gh
+actors Generative App → documented Actor runtime capabilities
+```
+
+A bounded process port uses executable plus argument arrays, an explicit working directory, output limits, timeout, cancellation, and redacted evidence. Shell interpolation is not the default contract.
+
+```js
+const result = await run({
+  command: "playerctl",
+  args: ["metadata", "--format", "{{artist}} — {{title}}"],
+  timeoutMs: 10_000
+});
+```
+
+A generic `exec(arbitrary-shell-command)` Generative App is forbidden. It would turn Telegram into a remote terminal, bypass bounded capability ownership, and violate the mobile companion boundary. A direct button click authorizes only the installed app method and its validated argument, never arbitrary process execution.
+
+## Live Views
+
+A Generative App sends a new message after a successful bound user action by default. This simple mode preserves prior surfaces and their visibly selected buttons, is robust across ordinary Telegram constraints, and remains a first-class behavior rather than a fallback to eliminate. A method may opt into `viewMode: "edit"` to replace the callback message and keyboard in place; if that explicit action cannot edit a deleted or otherwise unavailable message, it may send one fresh view because the click itself supplies recreation authority.
+
+Automatic refresh is not implemented in the current runtime. The intended future contract uses an exported `refresh` method and a bounded scheduling hint; applications must not return or rely on that hint until the backlog item is complete:
+
+```js
+export async function refresh({ state, run }) {
+  return {
+    output: await renderPlayer(state.player, run),
+    refreshAfterMs: 5000
+  };
+}
+```
+
+The runtime contract is:
+
+- Missing `refreshAfterMs` stops automatic refresh.
+- Values below two seconds clamp to two seconds.
+- The next interval starts only after the prior refresh and Telegram edit settle; calls never overlap or accumulate.
+- One refresh schedule exists per app, profile, target, and logical surface.
+- An unchanged normalized frame digest causes no Telegram edit.
+- Telegram `retry_after`, bounded backoff, lifecycle cancellation, target authority, and execution generation remain authoritative.
+- Refresh is session-bound and does not silently resume after process replacement until the surface is opened again.
+- Output-only refresh does not change `state.json` or append `states.jsonl`.
+
+The runtime retains the latest `TelegramDeliveryHandle` in memory for each live app surface. The first frame sends a logical view; later app actions and refreshes edit that same view rather than creating message traffic.
+
+Telegram does not reliably report deletion of every ordinary private bot message. When a supported deletion update identifies the handle, the runtime invalidates it immediately. When edit returns a known message-not-found result, the runtime forgets the handle and stops refresh. It never recreates a user-deleted view automatically; the next explicit user action or app opening may create a fresh view.
+
+## Lifecycle And Safety
+
+Generative Apps are trusted local code and therefore an explicit capability grant, not a sandbox promise. The runtime still narrows accidental authority and operational failure:
+
+- Installation validates canonical paths and rejects traversal, symlinks outside the managed root, identity mismatch, and silent replacement; explicit replacement stages and initializes the new app before swapping it under the same app.
+- App execution cannot own Telegram polling, credentials, raw transport, Pi queue state, or another app's files through the provided contract.
+- Per-app transitions serialize and compare immutable installation generation plus state revision so stale buttons cannot cross replacement or mutate newer state.
+- State commit and Telegram effect ordering are explicit; ambiguous non-idempotent transport outcomes never replay blindly.
+- Time, output, state-size, refresh-rate, and process bounds prevent one app from monopolizing the extension.
+- Session/profile/target generation replacement makes old scheduled work inert.
+- Diagnostics redact secrets and preserve app name, method, revision, failure class, and bounded stderr/result evidence.
+- Removal cancels refresh, invalidates the live binding, and keeps destructive state deletion as a separate explicit operation.
+
+## Application Roles
+
+The runtime supports two ownership roles without shipping application templates:
+
+- A standalone deterministic app owns its complete application state and transition rules. Poker-like games are the reference shape for app-owned state, not a bundled catalog entry.
+- A view/controller adapter owns only validated adapter configuration and a last-observed projection. A music-player remote is the reference shape: the Actor remains authoritative, while the Generative App samples structured status, invokes bounded controls, and renders the next view.
+
+Both roles use the same module, state, bound-action, and safety contracts. Selection and authoring procedure belong to the bundled `generative-apps` Skill.
+
+## Validation Contract
+
+Implementation is not complete until evidence covers:
+
+- Canonical path identity, direct app discovery, copy/install, explicit replacement with failure preservation, removal, and traversal rejection.
+- Mandatory `init`, named method dispatch, no-argument and strict-JSON argument parsing, missing exports, and result validation.
+- Transactional initialization, state/history equality, concurrent/stale actions, partial journal recovery, and output-only methods.
+- CML and full JSON button equivalence, inference bypass before Pi queue admission, absent-owner failure, and unchanged native callback routing.
+- Direct classic, leader, and follower target delivery with generation fencing and no model turn.
+- CLI process timeout, cancellation, output bounds, stderr diagnostics, and arbitrary-shell rejection.
+- Live-view handle retention, unchanged-frame suppression, two-second minimum, non-overlap, coalescing, Telegram backoff, deletion invalidation, message-not-found handling, and lifecycle cancellation.
+- Poker-style internal state and media-style external-state reference applications.
+
+The canonical open implementation work remains in [`../BACKLOG.md`](../BACKLOG.md). This document owns the proposed subsystem contract and its architectural boundaries.

package/docs/multi-instance-bus.md

@@ -316,7 +316,7 @@ Threaded Mode should make follower threads behave like normal Telegram instance
 | Surface                          | Leader behavior                                                                                                                                                                                                                                       | Follower requirement                                                                                                                                                                                                                                            | Routing/ownership invariant                                                                                                                                                                                                                         | Regression evidence                                                                                                       |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | Prompt intake                    | Thread prompt queues locally                                                                                                                                                                                                                          | Thread prompt is forwarded and queued by the owning follower                                                                                                                                                                                                    | Target ownership routes by `{ chatId, threadId }` before local handling                                                                                                                                                                             | Routing tests for foreign target message forwarding                                                                       |
-| Queued-message removal reactions | 👎/👻/💔/💩/🗑 removes pending prompt/media turn                                                                                                                                                                                                       | Same reaction on a queued follower prompt removes that follower's pending turn before dispatch                                                                                                                                                                  | When the leader forwards a prompt to a follower, it records `chatId/messageId -> follower instance` because Bot API reaction updates expose chat/message but not thread id                                                                          | Update runtime regression records forwarded message ownership and forwards the later reaction                             |
+| Queued-message removal reactions | 👎/👻/💔/💩/🗑 marks a pending prompt/media turn for deletion when it reaches dispatch                                                                                                                                                                            | Same reaction on a queued follower prompt marks that follower's pending turn for deletion before model dispatch                                                                                                                                                                  | When the leader forwards a prompt to a follower, it records `chatId/messageId -> follower instance` because Bot API reaction updates expose chat/message but not thread id                                                                          | Update runtime regression records forwarded message ownership and forwards the later reaction                             |
 | Queue priority reactions         | 👍/⚡/❤/🕊/🔥 prioritizes queued prompts                                                                                                                                                                                                               | Same reactions prioritize follower queued prompts                                                                                                                                                                                                               | Reaction forwarding uses stored message ownership, then follower mutates its local queue                                                                                                                                                            | Reaction mutation tests plus forwarded-reaction coverage                                                                  |
 | Message edits                    | Edits update matching queued prompt text                                                                                                                                                                                                              | Edits in a follower thread update that follower's queued prompt                                                                                                                                                                                                 | Message target ownership forwards edits to the owning instance; stored message ownership is the fallback when Telegram edit payloads omit thread id                                                                                                 | Update routing tests for foreign target and message-owned edited-message forwarding                                       |
 | Callbacks/buttons/menus          | Callback handled by the owning instance/menu state                                                                                                                                                                                                    | Follower callbacks are forwarded to the owning follower; follower menu sends/edits/deletes route through leader transport                                                                                                                                       | Leader records ownership for follower-sent Bot API messages so callbacks can route by message id even when Telegram omits thread id; Bot API edit/delete lacks thread id, so follower bus allows validated same-chat message operations             | Callback forwarding, generated-button target, bus follower-sent ownership, and bus edit/delete allowlist tests            |