11. Substrate versioning (V1–V6)
Часть RENAR Standard v1.0-draft · ← Оглавление
11.1 Назначение главы
Глава нормирует шесть capabilities (V1–V6), которые любой substrate обязан обеспечить чтобы реализовывать RENAR. Concept-level обоснование — в §5.5 (Утверждение 3 из «Положения в типологии методологий»). Эта глава даёт детальную нормативную формулировку каждой capability с pre/post-conditions, обоснованием через SoT chain, и mapping-примерами для основных substrate.
Конкретный инструмент версионирования (distributed VCS, централизованный VCS, document-oriented store с conflict resolution, иной механизм) interchangeable. RENAR нормирует capabilities, не tools.
11.2 Обоснование обязательности
Утверждение 1 из §5.3 (SoT inversion) физически невозможно реализовать без honest versioning. Структурная связь — направленная, не операционная:
| Capability отсутствует | Что становится невозможным | Цепочка через RENAR |
|---|---|---|
| V1 (immutable history) | «Реализация собрана против требований по состоянию на дату X» | provenance, audit trail, accepted gate |
| V2 (atomic change unit) | Гарантированная согласованность изменений | delta-ADAPT как atomic unit (см. §7.6) |
| V3 (diff & review) | Approval требований и спецификаций | quality gates QG-ADAPT-approve, QG-spec-approved |
| V4 (branching / change-set) | WIP отделим от утверждённой правды | draft → review → approved transitions |
| V5 (version pin) | Pinning версии требования из реализации | поле verifies[].requirement-version в TC (§9) |
| V6 (author + timestamp) | Provenance каждого изменения | подписи в ADAPT approval, AI-provenance в SR/SPEC |
Поэтому substrate, не удовлетворяющий V1–V6 (плоский файловый сервер без history; document store без conflict resolution; иные механизмы без immutable change tracking), не реализует RENAR независимо от других свойств. Это структурное, не операционное ограничение.
11.3 Нормативные определения V1–V6
Параграфы §11.3.1–§11.3.6 — substrate-agnostic. Конкретные substrate упоминаются только в §11.4 (mapping таблица как пример реализации) и §11.6 (примеры нормативного языка).
11.3.1 V1 — Immutable history
Capability: substrate обязан обеспечить, что для любого артефакта в его хранении любое прошлое состояние артефакта адресуемо и восстановимо без потерь.
Pre-conditions: артефакт зарегистрирован в substrate как объект versioning.
Post-conditions: для любого момента времени T в истории артефакта существует stable identifier версии, через который состояние артефакта на момент T полностью восстанавливается.
Negative — что без V1 невозможно:
- Восстановление состояния артефакта на дату подписания контракта.
- Сравнение текущего состояния с baseline.
- Audit trail для compliance (глава 14 §14.4).
- Отсчёт base point для delta-ADAPT.
Конкретные substrate-нативные реализации — см. §11.4.
11.3.2 V2 — Atomic change unit
Capability: substrate обязан обеспечить, что любое изменение артефакта (или согласованной группы артефактов) фиксируется как одна транзакция: всё или ничего. Промежуточные несогласованные состояния не наблюдаемы наружу.
Pre-conditions: substrate имеет понятие «транзакции» (atomic change).
Post-conditions: после atomic change либо все изменения видимы наблюдателю substrate, либо ни одно. Промежуточный split-brain недопустим.
Negative — что без V2 невозможно:
- Согласованное обновление BR + связанных SR одной транзакцией.
- Гарантия consistency между требованием и его
linked-tasks[]метаданными. - ADAPT approval как atomic act (двойная подпись + переход
client-ready → approvedза одну транзакцию). - Откат изменения без полу-применённого состояния.
11.3.3 V3 — Diff & review
Capability: substrate обязан обеспечить, что предложенное (но ещё не интегрированное) изменение представимо как diff против baseline, и человек или AI-агент с правом ревью может одобрить или отклонить это изменение до того как оно станет частью утверждённой правды.
Pre-conditions: предложенное изменение существует отдельно от утверждённой правды (см. V4).
Post-conditions: до approve — изменение существует, но не считается частью SoT. После approve — становится частью SoT atomic change unit’ом (V2).
Negative — что без V3 невозможно:
- Quality gates QG-ADAPT-approve, QG-spec-approved, QG-sr-approved (см. глава 10).
- Двойная подпись ADAPT (см. §7.5).
- Independent code review vs spec review (см. §5.3.3 (2)).
- Adversarial review как gate (см. research/02 принцип 2).
11.3.4 V4 — Branching / change-set
Capability: substrate обязан обеспечить разделение работы-в-процессе (WIP) от утверждённой правды (SoT) таким образом, что несколько independent изменений могут разрабатываться параллельно без взаимного влияния на SoT.
Pre-conditions: artifact зарегистрирован в substrate.
Post-conditions: для любого артефакта в данный момент могут существовать (a) ровно одна утверждённая версия (SoT) и (b) ноль или более WIP-черновиков, каждый из которых будет либо интегрирован через V3, либо отклонён.
Negative — что без V4 невозможно:
- Lifecycle статус
draftотделимый отapproved(глава 10). - Параллельная разработка нескольких delta-ADAPT.
- Backward findings в
asked-to-clientсостоянии без блокировки утверждённой правды. - Spec evolution с experimental SPEC-* версиями без воздействия на production-derived требования.
11.3.5 V5 — Cross-substrate version pin
Capability: substrate-A, использующий артефакт substrate-B, обязан иметь возможность зафиксировать конкретную версию артефакта substrate-B как stable cross-substrate identifier. Этот identifier должен быть resolvable substrate-B обратно к точно тому состоянию артефакта.
Pre-conditions: substrate-A и substrate-B оба удовлетворяют V1 (каждый имеет stable per-version identifier).
Post-conditions: для каждой зафиксированной ссылки в substrate-A на артефакт substrate-B существует pair (artifact-id, version-id), и через этот pair полное состояние артефакта substrate-B на момент pin восстановимо.
Negative — что без V5 невозможно:
- Поле
verifies[].requirement-versionв TC (глава 09 §9.4). - Pin реализационного substrate (где живёт код) на конкретную версию requirements substrate (где живут SR/SPEC).
- Garantия «эта реализация прошла приёмку против требований версии X».
- TC freshness metric (TC с pinned version старше текущей → stale).
11.3.6 V6 — Author + timestamp
Capability: substrate обязан обеспечить, что для каждой atomic change unit (V2) зарегистрирован identifiable author (человек или AI-агент с unique identifier) и timestamp с не хуже секундной точностью.
Pre-conditions: substrate имеет систему идентификации authors.
Post-conditions: для любой atomic change unit запрос who? when? возвращает однозначный ответ.
Negative — что без V6 невозможно:
- Двойная подпись ADAPT (signature = author + timestamp в substrate-нативной форме).
- AI-provenance во frontmatter артефактов (см. research/02 принцип 1).
- Compliance audit trail.
- Метрика adversarial-found rate (распределение backward findings по authors).
11.4 Mapping V1–V6 на конкретные substrate (пример реализации)
Эта таблица — пример того, как V1–V6 реализуются на распространённых substrate. Таблица не является частью нормативного контракта. Любой substrate, удовлетворяющий V1–V6 — независимо от того, представлен он в этой таблице или нет — реализует требования главы 11.
| Capability | Git | Mercurial | SVN | Perforce | CouchDB / Raven |
|---|---|---|---|---|---|
| V1 immutable history | commits, hash-chain | changesets, hash-chain | revisions, sequential numbering | changelists | revision tree per doc (_rev) |
| V2 atomic change unit | commit | commit | atomic revision | changelist submit | document update (single _rev advance) |
| V3 diff & review | Merge Request / Pull Request | hg phabricator, mq | svn diff + commit gate | swarm review | API workflow + Hub UI approval |
| V4 branching / change-set | branches | named branches, bookmarks | branches (copy semantic) | branches / streams | conflict branches / WIP docs / draft status |
| V5 cross-substrate version pin | submodule SHA | subrepo changeset | externals (peg rev) | branches / streams reference | _rev reference + created_by_order |
| V6 author + timestamp | commit metadata | commit metadata | revision properties | changelist metadata | doc fields (author, updated_at) |
Подробные практические workflow для каждого substrate — в:
11.5 Substrate, не удовлетворяющий V1–V6
Следующие конфигурации не реализуют RENAR, потому что нарушают одну или более capability:
| Конфигурация | Нарушение |
|---|---|
| Плоский файловый сервер с переименованием файлов как версионирование | V1 (нет stable history; renamed file = lost provenance) |
| Document store без conflict resolution | V2 (split-brain состояние возможно) |
| Wiki без revision history | V1, V6 |
| Wiki с revision history но без approval workflow | V3 |
VCS с principal mtime-versioning вместо immutable identifier | V1, V5 |
| Substrate, allowing in-place edit of historical revisions | V1 (history mutable — defeats audit) |
Команда, имплементирующая RENAR на substrate из этого списка, должна либо перейти на удовлетворяющий substrate, либо построить compensating layer обеспечивающий V1–V6 поверх базового хранения. В обоих случаях conformance manifest обязан явно документировать как V1–V6 реализуются.
11.6 Substrate-agnostic нормативный язык
Нормативные параграфы RENAR используют substrate-agnostic терминологию: «atomic change unit» (V2), «version pin» (V5), «approved» состояние (после V3), «WIP» (V4). Substrate-specific термины (имена конкретных инструментов и их primitives) допустимы только в:
- Иллюстративных таблицах и примерах с явной пометкой о substrate-specific характере (как §11.4).
- Cross-references на substrate-specific tool guides в guide/.
- Приложениях к нормативным главам.
11.6.1 Примеры substrate-agnostic нормативных формулировок
| Substrate-agnostic (нормативная форма) | Substrate-specific (НЕ нормативная) |
|---|---|
| «Изменение требования регистрируется как atomic change unit с автором и временем (V2, V6)» | «Изменение требования регистрируется в виде commit’а» |
| «Изменение проходит diff/review до интеграции (V3)» | «Изменение проходит Merge Request review до merge’а в main» |
| «Implementation substrate фиксирует конкретную версию requirements substrate (V5)» | «.src репозиторий фиксирует submodule SHA .req репозитория» |
| «Двойная подпись ADAPT регистрируется как два независимых author+timestamp events (V6)» | «Двойная подпись ADAPT — два approve clicks в Merge Request UI» |
| «При попытке изменить already-approved требование вне atomic change unit с явной review-процедурой — нарушение стандарта» | «Force-push на approved branch блокируется hooks» |
11.6.2 Substrate как параметр конформанса
Каждая команда, имплементирующая RENAR, фиксирует выбор substrate в conformance manifest с явным mapping V1–V6 → substrate-нативные primitives. При смене substrate (например, миграция с distributed VCS на document-oriented store) — manifest обновляется, и проводится regression test V1–V6 на новом substrate (см. §11.8).
11.7 Conformance manifest
Каждая RENAR-conforming имплементация публикует файл RENAR-CONFORMANCE.md в корне проекта со следующей структурой:
# RENAR Conformance Manifest
- **Проект**: <project-name>
- **RENAR Standard version**: v1.0
- **Claimed conformance level**: RENAR-N (см. глава 12)
- **Conformance date**: <ISO date>
- **Re-assessment due**: <ISO date>
## Substrate
| Substrate role | Tool / system | Version |
|---|---|---|
| Requirements substrate | <name> | <version> |
| Implementation substrate | <name> | <version> |
## V1–V6 mapping
| Capability | Native primitive | Validation method |
|---|---|---|
| V1 immutable history | <substrate-specific> | <CI check / manual> |
| V2 atomic change unit | <substrate-specific> | <CI check / manual> |
| V3 diff & review | <substrate-specific> | <CI check / manual> |
| V4 branching / change-set | <substrate-specific> | <CI check / manual> |
| V5 cross-substrate version pin | <substrate-specific> | <CI check / manual> |
| V6 author + timestamp | <substrate-specific> | <CI check / manual> |
## Mandatory clauses verification
- [ ] [§5.3](standard/05-methodology-positioning.md#5.3) SoT inversion: какие hooks обеспечивают
- [ ] [§5.4](standard/05-methodology-positioning.md#5.4) Waterfall-form: применимость задокументирована
- [ ] [§5.5/11](standard/05-methodology-positioning.md#5.5) Substrate versioning: V1–V6 mapping выше
- [ ] [§7](standard/07-adapt.md) ADAPT для каждого ТЗ
- [ ] [§8](standard/08-specifications.md) Closed list 9 SPEC types
- [ ] [§9](standard/09-test-cases.md) TC pos/neg парностьManifest обязателен для conformance claim уровня RENAR-1 и выше (см. глава 14).
11.8 Substrate migration
При смене substrate (например, миграция с одного механизма версионирования на другой) команда обязана выполнить следующее в порядке:
- Pre-migration audit: проверить, что целевой substrate удовлетворяет V1–V6. Если нет — миграция запрещена до compensating layer.
- Conformance manifest draft: подготовить обновлённый
RENAR-CONFORMANCE.mdс новым mapping. - Isomorphism verification: проверить, что все артефакты (BR, SR, SPEC, ADAPT, TC) переносимы без потери полей, ID или provenance. Все ID immutable — переименование при миграции запрещено.
- Atomic cutover: миграция выполняется как atomic change unit на уровне организационного процесса — одномоментный переход всех артефактов проекта на новый substrate. Параллельное использование двух substrate как SoT запрещено (см. §5.3.3 (1) и drift class 7.3 в research/00).
- Post-migration verification: regression test V1–V6 на реальных артефактах. Цель — убедиться, что каждая capability работает на новом substrate так же, как на старом.
- Conformance manifest commit: обновлённый
RENAR-CONFORMANCE.mdв новый substrate.
После атомарной миграции старый substrate становится либо архивом (read-only snapshot), либо упраздняется. Параллельная работа на двух substrate как SoT — запрещена нормативно.
11.9 Связь с другими главами
| Глава | Связь |
|---|---|
| 05 Methodology positioning §5.5 | Concept-level обоснование V1–V6 как одно из трёх mandatory утверждений |
| 06 Requirements hierarchy | Поля frontmatter требований опираются на V1 (immutable IDs), V5 (pinning) |
| 07 ADAPT | Approval двойной подписи опирается на V3 + V6; delta-ADAPT — на V1 + V2 + V4 |
| 08 Specifications | constrained-by[], depends-on[], referenced-by[] — графовые связи через V5 |
| 09 Test cases | verifies[].requirement-version — прямое применение V5 |
| 10 Lifecycle и QG | State transitions опираются на V2 + V3 + V4 |
| 12 Maturity model | На RENAR-3+ V5 cross-substrate pin обязателен; на RENAR-4+ V6 author + AI-provenance |
| 14 Conformance | RENAR-CONFORMANCE.md — обязательный артефакт |
| guide/03 — distributed VCS implementation | Substrate-specific практика |
| guide/04 — document-oriented store implementation | Substrate-specific практика |