Перейти к основному содержимому

Что можно и что нельзя редактировать вручную

Что это​

raytsystem строго разделяет неизменяемые (канонические и сырьевые) зоны и единственную зону для ручных правок. Это правило защищает воспроизводимость: если бы люди редактировали производные или канонические файлы напрямую, знание перестало бы быть проверяемым.

Чего НЕЛЬЗЯ касаться вручную​

Никогда не редактируйте напрямую (AGENTS.md, ADR-002, ADR-003):

  • _raw/ — точные неизменяемые байты источников (content-addressed). Хранилище только дополняется.
  • Объекты и поколения ledger — типизированные канонические записи в ledger/ и манифесты поколений. Это источник истины.
  • ledger/CURRENT — указатель на активное поколение.
  • Сгенерированные страницы knowledge/ — производные Markdown-представления. Прямые правки отклоняются, потому что каждая страница несёт ID поколения и должна пересобираться из ledger (ADR-003).
  • Служебные зоны вроде ops/events/ и outbox.

Если вы случайно изменили что-то из этого, восстановите производные из канона (см. Восстановление индексов) — каноническое сырьё и ledger при этом трогать не нужно.

Что МОЖНО редактировать​

Единственная зона, доступная человеку для правки, — knowledge/manual/ (ADR-003). Это ваши исходные статьи и заметки до того, как они станут знанием. Отредактированные вручную материалы возвращаются в базу знаний через операцию INGEST на общих основаниях: они проходят тот же конвейер prepare → validate → promote, что и любой другой источник. Прямого «короткого пути» в канон нет.

Раздел «Документы» даёт удобный редактор этой и других явно разрешённых зон, но не меняет эту границу: сохранение заметки не является promotion и не делает её canonical claim.

Одобрение промоушена​

Промоушен — единственный шаг, который меняет каноническое знание. Для реального корпуса он запрещён по умолчанию (default-deny). Когда вы пытаетесь промоутить реальный run, система переводит его в состояние awaiting_approval и требует ApprovalRecord, привязанный к точному хешу кандидата (src/raytsystem/ingestion.py).

Одобрение должно быть точным, срочным (с истечением) и связанным с хешем полезной нагрузки: оно проверяется внешним верификатором и принимается только из изолированной зоны входящих одобрений. Никакого «пакетного» разрешения на всё — каждое одобрение относится к конкретному кандидату. Подробнее — Одобрения и Настройки по умолчанию.

Реальный корпус против синтетических фикстур​

  • Реальный материал — всё, что не является явно одобренной фикстурой. Его промоушен всегда упирается в одобрение.
  • Синтетические фикстуры (--fixture) — только для материала, зарегистрированного в доверенном манифесте фикстур в заданном пространстве имён (по умолчанию tests/fixtures/). Байты сверяются с манифестом; незарегистрированные байты не проходят (src/raytsystem/ingestion.py). Фикстуры нужны для тестов и демонстраций и не открывают путь для реального корпуса.

Флаг --fixture не является «разрешением» — это узкий, проверяемый по манифесту режим. Использовать его для реальных источников нельзя.

Частые ошибки​

  • Правка сгенерированной страницы knowledge/ — изменения будут отклонены или затёрты при пересборке. Правьте источник в knowledge/manual/ и запускайте INGEST.
  • Попытка промоутить реальный источник без одобрения — run останется в awaiting_approval. Получите ApprovalRecord.
  • Ожидание, что --fixture пропустит реальный файл — байты не совпадут с манифестом, операция будет отклонена.

Связанные страницы​

Источники истины​

  • ops/decisions/ADR-003-ledger-and-markdown-views.md
  • ops/decisions/ADR-002-immutable-raw-and-evidence.md
  • src/raytsystem/ingestion.py
  • skills/raytsystem-ingest/SKILL.md
  • AGENTS.md