已关闭
[MVP-02] Define the harness-neutral domain and runtime contracts #4
urandon创建于  7月28日关闭于  7月29日
urandon
urandon成员
7月28日 创建

Parent and architecture

  • Implementation epic: #6
  • Architecture: #1
  • Depends on: #3

Outcome

Define stable Go domain types and ports so Telegram ingestion, YDB persistence, queues and AI harnesses can be implemented and tested independently.

Estimate

  • 5 SP / 3 engineering days
  • Risk: medium

Scope

  • Define tenant, Telegram user/chat, context epoch and explicit clean-context semantics.
  • Define Run, Attempt, Lease, Checkpoint, QuotaReservation, UsageObservation, ArtifactManifest, dispatch outbox and Telegram delivery outbox types.
  • Define state machines and allowed transitions for runs, provider quota state and delivery.
  • Define interfaces for clock/IDs, state store, queue, blob store, Telegram client, credential vault, harness driver and entitlement/quota observer.
  • Define versioned queue envelopes containing opaque IDs only.
  • Define structured error taxonomy: retryable, terminal, quota-blocked, re-authentication required and policy denied.
  • Define cancellation and idempotency contracts.

Design constraints

  • Telegram semantics remain the source of product context.
  • Queue messages never contain prompts, attachments or credentials.
  • One run belongs to one tenant and one subscription connection.
  • Unknown provider quota is represented explicitly; it is not fabricated from token estimates.
  • Domain packages do not import Yandex Cloud, Telegram transport or harness-specific SDK packages.

Non-goals

  • YDB query implementation.
  • Telegram webhook handler.
  • Codex App Server integration.

Acceptance criteria

  • Transition tables and invariants are covered by unit tests.
  • Invalid cross-tenant identifiers cannot be represented or are rejected at the boundary.
  • Queue envelopes are versioned and round-trip through JSON fixtures.
  • Fake implementations support deterministic tests with injected time and IDs.
  • The contracts support Codex first without naming Codex in core scheduling types.
likedislike
urandonurandon成员
7月28日 修改了issue 的描述
urandon
urandon成员
7月29日 评论:

README acceptance addendum for the next implementation PR

The PR implementing this issue must also update the repository README to match the current product direction:

  • Sessionless is a serverless, cloud-hosted agent execution platform, not a Telegram-specific bot implementation.
  • Telegram is the first frontend/transport adapter and the first source of conversation context, but the architecture must allow additional frontends without redefining the core domain.
  • The control plane and domain contracts remain harness-neutral. The project is evaluating Codex, OpenCode, Claude and Hermes-style harnesses; the README must not present any one of them as the final committed runtime.
  • Harness-specific behavior belongs behind worker/runtime adapters and isolated execution boundaries.
  • The README should distinguish the current repository foundation and skeleton binaries from capabilities that are planned but not yet implemented.
  • Architecture and implementation links should point readers to design issue #1 and implementation epic #6.

This README update is part of the next PR's acceptance, not a separate documentation follow-up.

likedislike
urandonurandon成员
7月29日 关联了pull request:MVP-02: define harness-neutral domain and runtime contracts
urandon
urandon成员
7月29日 评论:

Implementation result — harness-neutral contracts

Implementation is published in MR !3, commit d5dc031.

Delivered

  • internal/domain: tenant-scoped frontend/actor identities; explicit context epochs and clean-context events; runs, attempts, leases, checkpoints, quota reservations, usage observations, artifact manifests, dispatch outboxes and Telegram delivery outboxes.
  • Explicit, tested transition tables for run, attempt, dispatch, delivery, reservation and provider-quota states.
  • Unknown provider quota remains a first-class state and cannot carry fabricated remaining/reset values.
  • Cross-tenant composition is rejected for entities, blob prefixes, frontend delivery payloads, credentials and harness execution requests.
  • internal/queuecontract: strict sessionless.queue.v1 JSON envelopes with opaque IDs only; unknown fields, prompts and trailing JSON are rejected; both message kinds round-trip through committed fixtures.
  • internal/ports: clock/IDs, transactional state store, at-least-once queue, blob store, Telegram frontend adapter, credential vault, harness-neutral execute/cancel, entitlement/quota and durable-cancellation contracts.
  • internal/testkit: deterministic clock, sequence ID generator and at-least-once memory queue fakes.
  • docs/contracts.md: public transition tables, persistence/outbox semantics, cancellation/idempotency rules, isolation rules and port boundaries.
  • README updated as required by the acceptance addendum: Sessionless is now presented as a serverless cloud platform; Telegram is the first frontend; the control plane remains harness-neutral and does not commit to Codex, OpenCode, Claude or Hermes.

Verification

make ci                                                PASS
go test -race -count=10 ./internal/domain \
  ./internal/ports ./internal/queuecontract \
  ./internal/testkit                                   PASS
jq empty test/fixtures/queue/*.json                    PASS
make migrate-local                                     PASS (expected no-op)
git diff --check                                       PASS

The contract-package import audit is clean: no harness, Telegram SDK, Yandex Cloud SDK or YDB SDK dependency enters the domain/runtime contracts.

Issue #4 remains open until the GitHub mirror runs both Go verification and Runtime images successfully and MR !3 is merged. The final close will include the verified merge SHA and CI links.

likedislike
urandon
urandon成员
7月29日 评论:

Completion report

MVP-02 is accepted and ready to close.

Merge and source verification

  • MR !3 is merged.
  • GitCode main and GitHub mirror main both resolve to merge commit 5f3aab03b15af3bcc1740299b8ffa3b313eb8939.
  • The merged source tree exactly matches reviewed MR head d5dc031 (tree 245d7c2f468c2c0ab9a9e7f6456c3cff708469f9).

Final CI evidence

GitHub Actions run #4 completed successfully on the exact merge SHA:

Acceptance summary

  • Run, attempt, dispatch, delivery, reservation and provider-quota transition tables are implemented and unit-tested.
  • Cross-tenant entity composition, blob prefixes, frontend payloads, credential handles and execution requests are rejected at their boundaries.
  • sessionless.queue.v1 envelopes contain opaque IDs only, reject unknown/payload fields, and round-trip through committed JSON fixtures.
  • Deterministic clock, sequence-ID and at-least-once queue fakes support repeatable adapter tests.
  • Core scheduling and execution contracts remain harness-neutral and import no concrete harness, Telegram, Yandex Cloud or YDB SDK.
  • The README now presents Sessionless as a serverless cloud platform, Telegram as its first frontend, and all harnesses as replaceable worker adapters rather than a fixed product dependency.
  • State, queue, cancellation, idempotency, quota, artifact and worker-port contracts are documented in docs/contracts.md.

All acceptance criteria for #4 are satisfied.

likedislike
urandonurandon成员
7月29日 关闭了 issue
urandonurandon成员
8月26日 添加了label:designmvp
urandonurandon成员
8月26日 关联了里程碑:MVP — Core platform (#6)