@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-telegram/docs/delivery.md

@@ -0,0 +1,225 @@
+# Telegram Delivery API
+
+## Purpose
+
+The Telegram Delivery API gives trusted extension consumers a safe programmatic way to render operational Telegram UI without importing bridge internals or owning Telegram transport.
+
+It fills the boundary between callback-scoped `TelegramSectionContext.open()` and agent-callable `telegram_message` / `telegram_attach`. It does not replace normal active-turn final replies, Sections, outbound handlers, or raw update handlers.
+
+The public package membrane is:
+
+```ts
+import {
+  deleteTelegramView,
+  editTelegramView,
+  sendTelegramChatAction,
+  sendTelegramView,
+} from "@llblab/pi-telegram/delivery";
+```
+
+## Ownership Boundary
+
+Consumer extension code owns:
+
+- When an operational view should appear.
+- View text, parse mode, and optional inline keyboard.
+- Its own settings and callback policy.
+- Retaining a returned handle only for the current live extension generation.
+
+pi-telegram owns:
+
+- Active-turn and current-instance target resolution.
+- Pairing and target authorization.
+- Classic direct transport versus follower-to-leader routing.
+- Named-profile isolation.
+- Per-target operation ordering.
+- Telegram text limits, rendering, and chunk reconciliation.
+- Runtime generation checks, shutdown behavior, and diagnostics.
+- Bot credentials, polling, offsets, retries, and raw API clients.
+
+## Public Contract
+
+### Views
+
+```ts
+export type TelegramDeliveryParseMode = "plain" | "html" | "markdown";
+
+export interface TelegramDeliveryView {
+  text: string;
+  parseMode?: TelegramDeliveryParseMode;
+  replyMarkup?: TelegramInlineKeyboardMarkup;
+}
+```
+
+`plain` is the default. Operational activity should prefer `plain` or explicit `html`. `markdown` exists for extension-authored content that naturally owns Markdown; the bridge converts it through the existing UI/compat Markdown-to-HTML renderer rather than entering the native assistant final-reply pipeline.
+
+`replyMarkup` accepts only structural keyboard data. Callback ownership stays with Sections or a registered raw update handler. The documented issue #126 consumer shape uses Sections for interactive Settings toggles and keeps delivered activity rows non-interactive, so a second managed callback registry would duplicate token, answer, edit, navigation, and cleanup ownership without a proven use case. Revisit only when a public-import-only consumer must generate managed callbacks independently of a registered Section context for arbitrary delivered messages.
+
+### Target scopes
+
+```ts
+export type TelegramDeliveryScope =
+  | { kind: "active-turn" }
+  | { kind: "instance" }
+  | { kind: "aggregate" }
+  | { kind: "target"; target: TelegramDeliveryTarget };
+
+export interface TelegramDeliveryTarget {
+  chatId: number;
+  threadId?: number;
+}
+```
+
+Resolution rules:
+
+- `active-turn` requires a current Telegram-owned turn and resolves its exact `{ chatId, threadId? }`.
+- `instance` resolves the current process's assigned follower/leader thread, or the paired private chat in classic mode. It does not silently fall back to an unrelated active thread.
+- `aggregate` resolves the paired private chat without `threadId`; it is the Threaded Mode `All` surface and the ordinary classic chat. Follower aggregate messages carry an internal authenticated-bus marker that the leader validates for the assigned chat and strips before Bot API transport; unmarked or cross-chat threadless follower writes remain denied.
+- `target` validates an explicit destination against the active profile and current runtime authority. A classic owner may target its paired private chat. A follower may target only its assigned thread or aggregate surface. A leader may target its own thread, aggregate surface, or a currently live bound thread for that profile. Unknown, stale, cross-profile, and unpaired targets are rejected.
+
+No scope selects another named profile. Profile activation remains session-local bridge state.
+
+### Handles
+
+```ts
+export interface TelegramDeliveryHandle {
+  readonly target: TelegramDeliveryTarget;
+  readonly messageIds: readonly number[];
+  readonly generation: string;
+}
+```
+
+A handle represents one logical view, which may span multiple Telegram messages after chunking. `generation` is an opaque runtime identity, not an authorization secret. Callers must not construct handles or persist them across reload/session replacement.
+
+Edit reconciles the logical view as one operation:
+
+- Existing chunks are edited in order.
+- Additional chunks are sent when the new view grows.
+- Surplus old chunks are deleted when the new view shrinks.
+- The returned handle replaces the previous handle.
+
+Delete removes every message still represented by the handle. Partial transport failure returns a structured failure and records diagnostics; it never pretends the whole logical view succeeded.
+
+### Results
+
+```ts
+export type TelegramDeliveryFailureReason =
+  | "runtime-unavailable"
+  | "target-unavailable"
+  | "target-unauthorized"
+  | "stale-handle"
+  | "invalid-view"
+  | "commit-unknown"
+  | "transport-failed";
+
+export type TelegramDeliveryResult<T> =
+  | { ok: true; value: T }
+  | {
+      ok: false;
+      reason: TelegramDeliveryFailureReason;
+      message: string;
+      partial?: T;
+    };
+```
+
+Expected availability, authorization, lifecycle, and ambiguous mutation outcomes return failures rather than throwing. `commit-unknown` means a non-idempotent Bot API mutation may have committed before its response was lost; callers must not blindly replay it. When earlier chunks remain known, `partial` still carries their recoverable logical handle. Programmer errors may still throw for malformed objects that cannot satisfy the TypeScript contract. Transport failures are redacted before reaching callers and are also recorded in bridge runtime diagnostics.
+
+When a multi-chunk `send` or growing `edit` fails after materializing part of the logical view, `partial` contains a valid handle for every message still visible from that operation. Callers may pass it to `editTelegramView` to reconcile the view or to `deleteTelegramView` for cleanup. A failure before any message exists omits `partial`; callers must never infer message ids or construct a handle.
+
+### Operations
+
+```ts
+export interface SendTelegramViewOptions {
+  scope: TelegramDeliveryScope;
+  replyToMessageId?: number;
+}
+
+export function sendTelegramView(
+  view: TelegramDeliveryView,
+  options: SendTelegramViewOptions,
+): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+
+export function editTelegramView(
+  handle: TelegramDeliveryHandle,
+  view: TelegramDeliveryView,
+): Promise<TelegramDeliveryResult<TelegramDeliveryHandle>>;
+
+export function deleteTelegramView(
+  handle: TelegramDeliveryHandle,
+): Promise<TelegramDeliveryResult<void>>;
+
+export function sendTelegramChatAction(
+  action: "typing" | "upload_document" | "upload_photo" | "record_voice",
+  options: { scope: TelegramDeliveryScope },
+): Promise<TelegramDeliveryResult<void>>;
+```
+
+`replyToMessageId` applies only to the first chunk and must belong to the resolved chat. The initial contract exposes only actions already used by bridge-owned activity and delivery paths; it is not a generic Bot API action string.
+
+## Runtime Binding
+
+The public functions resolve a process-local runtime binding on every call. They never capture a Pi `ExtensionContext` or command context.
+
+The bridge constructs and binds a genuinely fresh delivery runtime during every `session_start`. It unbinds and shuts down the current runtime during `session_shutdown` before session-bound transport state is discarded; binding an unexpected replacement also shuts down the displaced runtime. Reload and session replacement therefore produce these outcomes:
+
+- A new call resolves the newly bound runtime after startup.
+- An old handle returns `stale-handle` for edit and delete.
+- A call while no generation is bound returns `runtime-unavailable`.
+- Queued operations from the old generation stop before transport begins.
+- An already-issued Telegram request may resolve during shutdown, but the old operation returns `runtime-unavailable` and cannot issue another edit, delete, chunk, or chat action afterward.
+- Old operations never adopt the replacement generation implicitly.
+
+The binding uses the same `globalThis` membrane pattern as other extension registries so package load order does not expose bridge internals. Only pi-telegram may bind or replace the runtime port.
+
+## Ordering And Delivery Semantics
+
+- Operations serialize per profile and concrete target. Different targets may progress independently.
+- `send`, logical `edit`, and logical `delete` preserve caller order for the same target.
+- Delivery uses the existing bridge API runtime so followers route allowlisted calls through the leader rather than contacting Telegram directly.
+- Text is chunked through the existing parse-mode-appropriate renderer/splitter. HTML chunks remain balanced, extension-authored Markdown becomes balanced UI/compat HTML, and plain chunks preserve text.
+- Inline keyboard markup attaches only to the final chunk of a logical view. Reply parameters attach only to the first chunk.
+- Edit growth sends additional chunks; edit shrink deletes surplus chunks; delete removes every chunk in handle order.
+- A partial send failure returns the ids already sent. A partial edit failure returns the original surviving ids plus every newly sent id, minus any surplus ids already deleted during shrink. The returned handle therefore remains sufficient for deterministic retry or cleanup.
+- The API does not participate in assistant preview/final deduplication and does not mutate the Telegram turn queue.
+- A successful operational send does not imply agent work, create a Pi prompt, or alter terminal status.
+
+## Diagnostics
+
+Failures record redacted runtime events under a delivery-specific category with operation, scope kind, profile, and failure reason. Diagnostics must not include bot tokens, unrestricted message bodies, callback payload secrets, or raw transport responses.
+
+A future `getTelegramDeliveryDiagnostics()` is unnecessary for the first slice because callers receive structured results and `/telegram-status` already owns bridge diagnostics. Add a dedicated diagnostics getter only if a real consumer needs registry-level introspection.
+
+## Security And Non-Goals
+
+The API does not expose:
+
+- Bot tokens or raw Telegram clients.
+- Arbitrary Bot API methods.
+- A second polling loop.
+- Cross-profile delivery.
+- Unrestricted cross-instance targeting.
+- Session replacement, reload, process launch, or Pi slash-command dispatch.
+- File/media uploads in the first 0.21 slice.
+- Captured Pi contexts or mutable queue/session state.
+
+Extension consumers remain trusted local code, but the contract still preserves product ownership boundaries so accidental misuse cannot silently bypass Threaded Mode routing or target identity.
+
+## Validation Contract
+
+The implementation must cover:
+
+- Classic `instance` and `aggregate` resolution.
+- Leader own-thread, aggregate, and live-bound explicit target resolution.
+- Follower assigned-thread and aggregate routing through the leader.
+- Missing active turns and disconnected runtimes.
+- Cross-profile, unknown, stale, and unauthorized explicit targets.
+- Plain, HTML, and Markdown chunking.
+- Reply-first and keyboard-last chunk placement.
+- Send/edit growth/edit shrink/delete ordering.
+- Reload/session-replacement generation invalidation.
+- In-flight shutdown fencing and redacted diagnostics.
+- Package-boundary imports with no `/lib` access.
+
+## Relationship To Activity
+
+The Activity API builds on this contract rather than duplicating transport. Activity handlers receive a fresh target-aware context whose `send`, `edit`, `delete`, and chat-action methods delegate to the same delivery runtime. The Activity API owns lifecycle normalization; this API owns delivery only.

package/node_modules/@llblab/pi-telegram/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.