kinderp / kinderp/durex

Define the transport-neutral Durex control API

Open
#41 0 comments 0 reactions 0 assignees View on GitHub
area:runtime kind:design
Dominant language
Python
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Parent and milestone

- Parent issue: #23
- Milestone: not scheduled; design follows the local console and audit
contracts in #12-#14.

## Problem

Telegram currently invokes application behavior in process, while the roadmap
promises future web and mobile clients. Without stable query, command,
view-model, idempotency, authentication, and event-stream contracts, a GUI
would either depend on Telegram rendering or query persistence directly.

## Outcome

Define a transport-neutral Durex control API that Telegram can consume in
process and future authenticated HTTP/SSE or WebSocket adapters can expose
without changing task, runtime, interaction, or plugin ownership.

## Scope

- Define versioned task, run, worker, interaction, usage, and pipeline view
models.
- Define query and command services with structured errors and idempotency
keys.
- Define cursor-based live-output and event-stream contracts.
- Define authentication, authorization, redaction, optimistic concurrency, and
audit requirements for a future network adapter.
- Keep Telegram rendering and callback payloads outside the application
contract.
- Define compatibility and schema-generation requirements for web and mobile
clients.
- Keep the base API independent of any specific runtime adapter. Runtime data
uses normalized identifiers and capabilities, with later additions reviewed
against #26.

## Non-goals

- Building the web or mobile GUI in this issue.
- Exposing SQLite, runtime SDKs, plugin processes, or Codex/OpenCode/Pi servers
directly.
- Opening an unauthenticated network listener.
- Waiting for a particular external runtime before defining task, run, worker,
interaction, and output contracts.

## Acceptance criteria

- [ ] Telegram console operations can be expressed entirely through the query
and command contract.
- [ ] DTOs do not contain Telegram payloads, SQLite rows, process ids, or
provider SDK objects.
- [ ] Mutating commands define authorization, idempotency, concurrency, and
audit behavior.
- [ ] Live output and normalized events have bounded cursor/resume semantics.
- [ ] Runtime-facing fields use provider-neutral identifiers and capabilities.
- [ ] A fake client conformance suite covers queries, commands, stale state,
replay, and authorization failure.
- [ ] API, security, compatibility, and future-client documentation is
included.

## Validation

- Review against #12 live console, #13 interaction audit, and #14
configuration contracts.
- Review runtime-facing extensions against #26 before they become public.
- Validate generated schema fixtures and a fake in-process adapter before
adding HTTP.

## Dependencies

- #12, #13, and #14 establish the initial application-service boundary.
- #26 is a coordination contract for later runtime-facing fields, not a blocker
for the base transport-neutral API.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the live console, interaction audit, and configuration contracts in issues #12, #13, and #14, then check runtime-facing extensions against #26. Define the transport-neutral query and command contracts, view models, event semantics, and security requirements without exposing Telegram or persistence details. Done means the listed acceptance criteria are covered, including schema fixtures and a fake in-process adapter.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend-api-design, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.