Pulse Pre-Implementation Freeze Package

Версия: v0.7 · Синхронизация: spec v0.14.3 · Последнее обновление: 2026-05-20

Машинно-читаемые артефакты, без которых нельзя начать M0 implementation. Эти файлы — single source of truth для контрактов, эндпоинтов и схем БД. Все codegen-инструменты должны читать отсюда, не из spec.md.

См. также: specification.md — архитектура; testing.md — testing strategy; marketing-patterns.md — pattern library.

---

Состав

Meta-schemas и infrastructure

Файл	Назначение	Статус
telemetry-contract-schema.yaml	JSON Schema для самого Telemetry contract (meta-schema)	M0 baseline
action-contract-schema.yaml	JSON Schema для Action contract (meta-schema)	M0 baseline
consent-purposes.yaml	Полный реестр consent purposes v0.1 (Pulse loads at startup)	M0 baseline
openapi.yaml	OpenAPI 3.1 для M0 HTTP API pulse-core	M0 baseline
ddl/01_identity_mapping.sql	DDL отдельной БД identity-mapping	M0 baseline
ddl/02_pulse_curated.sql	DDL Directus-managed схемы в shared Postgres	M0 baseline
ddl/03_pulse_runtime.sql	DDL Pulse-core-managed схемы в shared Postgres	M0 baseline

M0 contract instances (v0.1.0, App-focused)

Файл	Назначение	Статус
telemetry/v0.1.0.yaml	M0 Telemetry contract: 35 event-types (app., billing., pulse_internal.*) с sampling	M0 active
actions/v0.1.0.yaml	M0 Action contract: 4 actions с retry_policy + dispatch_timeout + requires_subject_fields	M0 active
semantic-layer/v0.1.0.yaml	M0 Semantic Layer: 12 dimensions, 14 metrics, 3 cohorts, explicit refresh policies	M0 active
test-corpus/	30 valid events + 10 invalid events + 4 valid action dispatches	M0 active
event-types-overview.md	Human-readable таблица всех 35 event-types	M0 active
validate.py	Cross-contract validator (CI gate) — 13 checks	M0 active
validate_enums.py	DDL ↔ openapi ↔ action-contract enum parity (CI gate)	M0 active

Что НЕ входит

• M1+ event types и actions — расширения контрактов идут отдельными версиями (v0.2.0, v0.3.0, …) в тех же каталогах telemetry/, actions/, semantic-layer/.
• M1+ API endpoints — добавляются итеративно в openapi.yaml.
• Migration scripts между версиями контрактов — отдельный каталог migrations/ появится в M2.
• DSL grammar — отдельный документ dsl-grammar.md (TBD, до M1).
• M1+ таблицы БД. DDL в этом пакете охватывает только M0 baseline. Таблицы, упомянутые в spec для последующих milestones (например, pulse_curated.launch_events из §17.7 — M3; future ML-registry, future LLM-conversation log) добавляются отдельными DDL-файлами по мере поступления соответствующих milestones. См. roadmap §15.
• Seed-файлы и секреты. seed_*.sql (consent_purposes, marketing_patterns, federation_root_keys, audit_genesis, allowed_callers production keys) — не часть freeze package; генерируются bootstrap-pipeline'ом из spec/contracts/ceremony output (см. §10.6.2).

Версионирование

Каждый файл имеет независимый версионер в header:

• schema_version — версия самой meta-schema (меняется редко).
• content_version — версия содержимого (для consent-purposes.yaml, увеличивается при изменении набора).

Сам этот пакет версионируется согласно specification.md общим versioner'ом Pulse.

Codegen

Эти артефакты — исходный код для генерации:

contracts/telemetry-contract-schema.yaml  ─► Rust types (typify)
                                          ─► TypeScript types (json-schema-to-typescript)
                                          ─► JSON Schema validator embedded в pulse-core ingest
                                          ─► OpenAPI components для /api/events/ingest

contracts/action-contract-schema.yaml     ─► Rust types для Action dispatcher
                                          ─► TS типы для Directus action editor
                                          ─► LLM tool catalog generator

contracts/consent-purposes.yaml           ─► initial seed в Consent Store
                                          ─► Rust enum ConsentPurpose
                                          ─► TS типы для App Settings → Privacy UI

contracts/openapi.yaml                    ─► Server stubs (utoipa или генератор)
                                          ─► TS client (openapi-typescript)
                                          ─► API documentation portal

contracts/ddl/*.sql                       ─► sqlx migrations
                                          ─► sqlx::query! type checks в Rust
                                          ─► Directus schema snapshot (для pulse_curated)

Изменения этого пакета

Любое изменение файла из этого пакета:

1. Triggers full CI suite (schema validate, snapshot tests, codegen regen).
2. Требует apparoval минимум 2 reviewers.
3. Записывается в changelog соответствующего файла + spec changelog.

В production-канале pulse/main действует content-addressed versioning (см. spec §5.2). Эти YAML/SQL — исходники, blake3-хеш которых определяет contract_id.