[SESSION-01] Define canonical session and event domain contracts-sessionless-AtomGit

已关闭

[SESSION-01] Define canonical session and event domain contracts #20

urandon创建于 8月3日关闭于 8月5日

urandon成员

8月3日创建

Parent and architecture

Implementation epic: #6
Accepted architecture decision: #1

Outcome

Replace the Telegram-authoritative conversation contract with frontend-neutral, platform-owned canonical session and event domain contracts before changing persistence adapters.

Estimate

5 SP / 3 engineering days
Risk: high

Scope

Define stable IDs and invariants for Session, SessionEvent, FrontendBinding, SessionParticipant and SessionSnapshot.
Define event kinds, strict per-session ordering, idempotency keys, participant roles, archive state and session lifecycle transitions.
Add session_id and trigger_event_id to the harness-neutral run/work contracts.
Define frontend-neutral application operations for create, bind/switch, append, archive, unarchive, list and history.
Retire context_epoch as a reset boundary. Snapshot version remains materialization metadata only.
Define assistant/tool-event finalization and frontend-projection semantics without binding the domain to Telegram.
Define stateless worker context-input contracts from snapshots plus ordered event ranges.
Update repository public direction and contracts in the same PR:
- AGENTS.md;
- README.md;
- docs/contracts.md;
- relevant architecture links and terminology.
Add unit tests for invariants and transition tables.

Non-goals

YDB migrations or adapter implementation.
Telegram handler changes.
Object Storage lifecycle rules.
Session history HTTP API implementation.
Harness-specific session persistence.

Acceptance criteria

Sessionless, not Telegram or a harness database, is unambiguously authoritative in every updated contract.
/new has one meaning: create a new canonical session and switch a frontend binding.
No overlapping context_epoch reset semantics remain in domain APIs.
Canonical events are append-only and tenant/session scoped.
Harness-native IDs are attempt metadata only.
Domain tests cover duplicate append, invalid participant access, archive/unarchive and stale binding transitions.
Public documentation is English and contains no implementation claims unsupported by executable code.

urandon成员

8月4日关联了pull request：SESSION-01: define canonical session and event contracts

urandon成员

8月4日评论：

Implementation update — canonical session contracts

Implementation is published in MR !18, branch ai/session-01-canonical-contracts, commit b601f06.

Implemented

Added stable UserID, SessionID, SessionEventID, FrontendBindingID, and SessionSnapshotID identities.
Added the canonical Session, append-only SessionEvent, optimistic FrontendBinding, tenant/user-scoped SessionParticipant, immutable SessionSnapshot, and snapshot-plus-contiguous-events context contracts.
Enforced exact-retry idempotency, conflict detection, strict per-session sequence progression, active/archive transitions, participant access, stale binding rejection, and event-kind ownership rules.
Added a frontend-neutral SessionStore boundary for create, atomic create-and-switch (/new), bind/switch, append, archive/unarchive, list, and ordered history.
Replaced Conversation/ContextEpoch in Run with canonical session_id and trigger_event_id, and propagated both IDs through worker jobs and harness execution requests.
Removed the domain ContextEpoch and CleanContextEvent APIs.
Updated AGENTS.md, README.md, and docs/contracts.md in public English to make Sessionless authoritative and Telegram/harnesses adapters.

Compatibility boundary

This issue deliberately does not implement the canonical YDB schema or new Telegram handlers. The existing Telegram/YDB adapter now exposes its old counter only as LegacyContextRevision and derives stable temporary session/event IDs. This keeps the current executable slice working without treating the legacy counter as a product API; #21, #22/#36, and #23/#37 remove that bridge.

Verification

make ci passed: generate, vet, race tests, all nine binaries, and foundation integration tests.
ydbintegration, localintegration, and e2elocal tagged suites compile successfully.
git diff --check passed.
The GitCode push mirror reached finished; GitHub Actions is now the remaining merge gate.

Issue remains open until mirrored CI is green and MR !18 is merged.

urandon成员

8月5日评论：

Completion report

MR !18 was squash-merged into main as commit cddf901.

The canonical session and event contracts are now implemented and documented. The same change also makes local startup schema-safe: make dev-up starts infrastructure, waits for YDB, applies migrations, and only then starts schema-dependent services. A clean-volume verification confirmed that application services no longer emit missing-table noise during database bootstrap.

Post-merge GitHub Actions is fully green: run 30922860994.

Go verification: passed
YDB schema and state store: passed
Local multi-service stand, including clean initialization and restart preservation: passed
Terraform environments: passed
Runtime images: passed

The acceptance criteria for this issue are satisfied.

urandon成员

8月5日关闭了 issue

urandon成员

15 天前添加了label：mvpsession

urandon成员

15 天前关联了里程碑：MVP — Core platform (#6)