Parent and architecture

• Implementation epic: #6
• Accepted architecture decision: #1
• Depends on: SESSION-01 #20, YDB partitioning #16

Outcome

Implement the authoritative YDB schema and Object Storage manifest layout for canonical sessions, ordered events, bindings, participants and snapshots using bounded tenant-scoped access paths.

Estimate

• 8 SP / 5 engineering days
• Risk: high

Scope

• Add migrations for:
  • sessions;
  • session_events;
  • frontend_bindings;
  • session_participants;
  • session_snapshots;
  • session activity index rows;
  • runs-by-session index rows.
• Add session_id and trigger_event_id to runs and related atomic procedures.
• Remove the pre-production conversations + context_epochs schema from the canonical baseline. Do not build a row-level backfill, dual-read, shadow-write or compatibility adapter for existing local/cloud-dev records.
• Implement atomic sequence allocation, event append, session last-activity update and index maintenance.
• Implement point/bounded-prefix reads for:
  • session by ID;
  • frontend binding;
  • ordered event page;
  • snapshot versions;
  • runs by session;
  • active/archived sessions by owner/recent activity.
• Use fixed fan-out owner/status activity buckets derived from random session IDs; do not use a global chronological primary key.
• Define session-scoped Object Storage keys and manifest validation for event payloads, attachments and compressed immutable snapshots.
• Keep canonical session/event metadata free from TTL.
• Update:
  • docs/ydb-state-store.md;
  • docs/ydb-partitioning.md;
  • migration/recovery documentation.
• Add clean-schema, repeat-migration, tenant-isolation, concurrency and physical-partition contract tests.

Pre-production schema reset policy

There is no production conversation data and existing local/cloud-dev application data is disposable. Before the first production deployment:

• the repository may squash or rewrite the application migration baseline to match the canonical session model;
• local and cloud-dev application tables, migration ledger rows and Sessionless-owned dev Object Storage prefixes may be reset instead of migrated record by record;
• the reset must preserve Terraform/bootstrap state, cloud resources outside the application schema, Lockbox secrets, IAM configuration and unrelated bucket prefixes;
• a cloud-dev reset requires explicit environment identity checks (folder/database/bucket), an allowlisted non-production target and typed confirmation;
• no reset command may accept an unresolved environment, broad bucket/database target or production identifier;
• CI starts from an empty YDB/Object Storage fixture and proves the new head from zero;
• once the first production baseline is deployed, applied migrations become immutable and normal expand/migrate/contract rules resume.

The migration runner still owns checksums, locking and crash behavior. Disposable data removes compatibility work; it does not permit an unguarded destructive command.

Non-goals

• Telegram ingestion behavior.
• Worker context materialization.
• Lifecycle transition to COLD/ICE.
• Search indexes or semantic search.

Verification

• Concurrent event appends produce a strict gap-free sequence without duplicate event IDs.
• Two tenants cannot resolve each other's sessions, bindings, events, snapshots or indexes.
• Session/activity/event queries are point or fixed-fan-out prefix operations.
• Activity-index tests prove bounded fan-out and descending recent-session pagination.
• Operational TTL cleanup fixtures leave canonical rows untouched.
• A clean YDB Local instance can migrate repeatedly from zero to the new head.
• A guarded local/cloud-dev reset removes obsolete application tables, ledger state and owned fixture objects, then applies the canonical baseline successfully.
• Negative tests prove the reset refuses production/unknown targets and cannot address Terraform state or unrelated Object Storage prefixes.

Acceptance criteria

• Every canonical table and materialized index documents its primary key, partitioning rationale and query contract.
• No global time-ordered hot key is introduced.
• Archived metadata is retained without TTL.
• Runs reference canonical session and trigger event identities.
• Applied migrations, checksums and crash-recovery behavior remain compatible with the existing migration runner.
• No production data-preservation machinery is added for accidental pre-production structures.
• The canonical migration baseline contains no legacy conversation/context-epoch compatibility path.
• The destructive reset path is explicit, non-production-only, narrowly scoped and fail-closed.