Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 5 additions & 7 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ Important staging note:
`build` and `dump` use cases dispatch by `builder`:

- `builder=DESIGNER` uses the existing `DesignerDsl`.
- `builder=IBCMD` uses `IbcmdDsl` with `config import/apply` for build and `config export` for dump; for EDT build the EDT export step still produces Designer-format files first, and for EDT dump the reverse path first updates an internal Designer snapshot before EDT import/publication.
- `builder=IBCMD` uses `IbcmdDsl` with `config import/apply` for build and `config export` for dump; for EDT build the EDT export step still produces Designer-format files first, while EDT dump uses private per-IB Designer and configured-source shadows before merge/publication.
- Builder backends are expected to stay interchangeable for implemented builder scenarios. Functionality added for the Designer builder should also be available through the IBCMD builder, or the gap must be documented explicitly. Future Designer agent mode should be added behind the same use-case contract.
- Server infobase support is a target contract for all tools; file-only behavior must be documented as a current gap rather than treated as the permanent architecture.

Expand All @@ -128,10 +128,8 @@ Constraints to keep in mind:

## Dump And Artifact Publication

Full replacement outputs are published through a staging/backup contract governed by [ADR-0015](spec/decisions/0015-atomarnaya-publikatsiya-dump-artifacts-cherez-staging-backup.md).
Full dump writes to a sibling staging directory before replacing the resolved target directory.
Package artifacts write to a sibling staging file before replacing the output file, and external EPF/ERF publication stages the whole output directory before replacing it.
Incremental and partial dump modes remain direct non-atomic update modes.
Package and external EPF/ERF artifacts use the sibling staging/backup contract from [ADR-0015](spec/decisions/0015-atomarnaya-publikatsiya-dump-artifacts-cherez-staging-backup.md).
All dump modes instead execute in private per-IB shadows and publish only managed files through the recoverable manifest transaction from [ADR-0023](spec/decisions/0023-izolirovat-runtime-state-po-infobase-i-ispolzovat-private-shadow.md). A B/S/D conflict publishes nothing; incremental and partial requests are promoted to one full shadow operation when their private baseline is unavailable.

## Output Flow

Expand All @@ -153,9 +151,9 @@ Use cases now return transport-neutral payloads or structured failures.
- `workPath/convert/out/<sourceSetName>/<designer|edt>/` stores default generated convert outputs; `convert --output <dir>` publishes the same converted source-set content under a caller-provided root using source-set path mirror layout.
- `workPath/temp/partial-lists/` stores partial load and partial dump list files.
- `workPath/temp/yaxunit/` stores temporary YaXUnit config files.
- `workPath/hash-storages/` remains reserved for change detection state.
- `workPath/ib-state/v1/<infobase-fingerprint>/<source-set>-<context-fingerprint>/` stores opaque per-IB change-detection state, private CDFI, baselines and recoverable transactions. Legacy `workPath/hash-storages/` is not migrated or reused.
- `workPath/designer/<sourceSetName>/` is used by the EDT export/build flow as the generated Designer-format output area for a source-set.

The `source-set` and `workPath` state boundary is formalized in [ADR-0002](spec/decisions/0002-izolirovat-runtime-state-po-source-set-pod-workpath.md): `DESIGNER` format uses one `designer-<sourceSetName>` change-detection context, while `EDT` format uses both `edt-<sourceSetName>` for export decisions and `designer-<sourceSetName>` for load decisions.
The source/runtime boundary is formalized in [ADR-0023](spec/decisions/0023-izolirovat-runtime-state-po-infobase-i-ispolzovat-private-shadow.md): every configured or generated view has a versioned identity scoped by infobase, source root, purpose, format, backend and logical role. EDT build still has distinct configured and generated Designer contexts, but dump platform/configured shadows live only in private transactions.
Exclusive command ownership of `workPath` is governed by [ADR-0011](spec/decisions/0011-eksklyuzivnoe-vladenie-workpath-na-vremya-komandy.md).
On-demand change detection and conservative file-level partial load rules are governed by [ADR-0012](spec/decisions/0012-on-demand-change-detection-i-faylovaya-partial-load-strategiya.md).
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 8 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,14 @@ reqwest = { version = "0.12", default-features = false, features = ["blocking",

[target.'cfg(windows)'.dependencies]
process-wrap = { version = "9.1.0", default-features = false, features = ["std", "job-object", "creation-flags"] }
windows-sys = { version = "0.61", features = [
"Wdk_Foundation",
"Wdk_Storage_FileSystem",
"Win32_Foundation",
"Win32_Security",
"Win32_Storage_FileSystem",
"Win32_System_IO",
] }

[dev-dependencies]
assert_cmd = "2"
Expand Down
10 changes: 10 additions & 0 deletions SKILL/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,16 @@ v8-runner --json-message build

Use text output for direct human diagnostics.

For JSON build and dump results, use each step's `receipt` as the exact source-sync audit record.
`requested` is the byte-exact add/modify/delete delta; `processed`, `skipped`, and `conflicted`
are independent audit dimensions, not a strict partition. In an applied result, the same target
may appear in both `processed` and `skipped` when it belongs to the effective platform scope but
publication retained or no-op'd the local version. Full operations report the complete managed
final scope; incremental/partial operations report observable shadow writes. Inconsistent overlap is invalid. `preHash`/`postHash` are SHA-256
values, with `null` denoting the absent side of an add/delete. Failed or cancelled steps keep the
computed `requested` delta and leave outcome lists empty; if failure happens before a delta can be
computed, every list may be empty.

Use `v8-runner version` or `v8-runner --version` to check the installed application version; it does not require `v8project.yaml`.

Useful global flags:
Expand Down
16 changes: 14 additions & 2 deletions SKILL/references/file-and-artifact-workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,19 @@ control characters are rejected. With `builder=DESIGNER`, Designer validates whe
metadata root type exists. With `builder=IBCMD`, the object list is not used because partial
degrades to incremental.

For `format=EDT`, dump uses an internal Designer snapshot under `workPath/designer/<sourceSetName>`, then imports the result into the EDT target.
For `format=EDT`, dump uses private platform and configured-source shadows inside the scoped
`ib-state/v1` transaction. The platform never writes the project source or
`workPath/designer/<sourceSetName>` as its dump target.

Dump safety and recovery rules:

- each infobase/source-set identity owns private shadows and generation-scoped baselines under `workPath/ib-state/v1`; fingerprints are opaque and state must never be reused across infobases;
- legacy `workPath/hash-storages` is deliberately not migrated; missing scoped state means full bootstrap, never an unchanged result;
- incremental and partial dump require a valid matching baseline and private `ConfigDumpInfo.xml`; missing or corrupt state promotes that one operation to a full dump;
- receipt lists are exact but independent audit dimensions: an applied target may be both `processed` and `skipped` when platform work occurred but publication retained/no-op'd it;
- a three-way conflict publishes no project-source files or new private generation;
- `B=absent, S=present, D=absent` is a conflict; runner never deletes a local file absent from its baseline;
- full, incremental, and partial modes all use recoverable manifest publication. Forward recovery requires the exact `(generation, UUID transaction token)`; otherwise it restores the previous managed file state.

## Convert

Expand Down Expand Up @@ -94,4 +106,4 @@ Behavior:
- external data processors and reports publish `.epf` / `.erf` into the output directory;
- `builder=DESIGNER` is required.

Full dump and package/external artifact publication use staged publication with backup/rollback semantics. Incremental and partial dump are non-atomic update modes.
Package and external-artifact publication uses staged backup/rollback semantics. Every dump mode uses journaled, manifest-scoped source publication and private-state recovery.
6 changes: 5 additions & 1 deletion SKILL/references/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,11 +47,15 @@ workPath/temp/<runner-id>/runs/<run-id>/

Useful `workPath` locations:

- `workPath/hash-storages/`: persisted change-detection state.
- `workPath/ib-state/v1/`: opaque per-infobase/per-source CDFI, baselines, observations, and recovery journals. Do not edit, copy between infobases, or delete it as a routine fix; legacy `hash-storages` is not migrated.
- `workPath/edt-workspace/`: shared EDT workspace for `init`.
- `workPath/convert/edt-workspace/`: separate EDT workspace for `convert`.
- `workPath/designer/<sourceSetName>/`: generated Designer representation, especially for EDT flows.
- `workPath/ibcmd-data/`: project-local standalone-server data for IBCMD dump; safe to remove only when no project command is running.
- `workPath/logs/platform/`: platform logs.
- `workPath/temp/partial-lists/`: Designer partial load/dump list files; failed partial-load builds preserve the relevant list file for diagnostics.
- `workPath/temp/`: temporary run artifacts and diagnostics.

If dump reports a three-way conflict, inspect `git diff` and resolve the local/source intent before
retrying. Conflict publishes no source files and advances no private generation. For a deliberate
build recovery use `v8-runner build --full-rebuild`; do not repair opaque state files manually.
29 changes: 20 additions & 9 deletions docs/CAPABILITIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,14 +26,14 @@ CLI help, доверяйте текущему коду и затем синхр
| `tools download <tool>` | CLI-only загрузка latest releases | Загружает выбранный YAxUnit, Vanessa Automation single или onec-client-mcp-devkit; обновляет local overlay для Vanessa/client MCP и при `yaxunit --sources` добавляет YAxUnit как `source-set` `tests` |
| `init` | `format=DESIGNER` + `builder=DESIGNER` | Создаёт файловую ИБ через Designer; server connection остаётся manual prerequisite |
| `init` | `format=DESIGNER` + `builder=IBCMD` | Выполняет `ensure` файловой или серверной ИБ через `ibcmd infobase create` |
| `init` | `format=EDT` + `builder=DESIGNER|IBCMD` | Готовит ИБ по правилам builder и импортирует EDT workspace |
| `init` | `format=EDT` + `builder=DESIGNER\|IBCMD` | Готовит ИБ по правилам builder и импортирует EDT workspace |
| `extensions` | `format=DESIGNER` или `format=EDT` | Обновляет свойства extension `source-set` |
| `build` | `format=DESIGNER` + `builder=DESIGNER|IBCMD` | Выполняет incremental/full загрузку в ИБ |
| `build` | `format=EDT` + `builder=DESIGNER|IBCMD` | Экспортирует изменённые EDT `source-set`, затем грузит generated Designer output |
| `build` | `format=DESIGNER` + `builder=DESIGNER\|IBCMD` | Выполняет incremental/full загрузку в ИБ |
| `build` | `format=EDT` + `builder=DESIGNER\|IBCMD` | Экспортирует изменённые EDT `source-set`, затем грузит generated Designer output |
| `test` | Та же матрица, что и у `build` | Всегда сначала запускает `build` |
| `dump` | `format=DESIGNER` + `builder=DESIGNER` | Полная, инкрементальная или object-scoped partial выгрузка |
| `dump` | `format=DESIGNER` + `builder=IBCMD` | Полная и инкрементальная выгрузка; `partial` деградирует в incremental с warning; standalone-server state изолирован в `workPath/ibcmd-data` |
| `dump` | `format=EDT` + `builder=DESIGNER|IBCMD` | Reverse sync из ИБ через internal Designer snapshot и EDT import |
| `dump` | `format=EDT` + `builder=DESIGNER\|IBCMD` | Reverse sync через private Designer/configured-source shadows и EDT import |
| `convert` | CLI-only repo-aware конвертация текущих `source-set` | Не использует `builder` и не требует ИБ |
| `load` | `format=DESIGNER` + `builder=DESIGNER` | Загрузка `.cf` / `.cfe` артефактов в ИБ |
| `make` / `artifacts` | `format=DESIGNER` + `builder=DESIGNER` | Экспорт `.cf` / `.cfe` и публикация `.epf` / `.erf` |
Expand Down Expand Up @@ -176,12 +176,17 @@ v8-runner build [--source-set <NAME>] [--full-rebuild]
- Для `DESIGNER` выбирает incremental, partial или full path по изменённым файлам выбранного scope.
- Для `EDT` сначала анализирует и экспортирует выбранные EDT `source-set`, затем грузит generated
Designer files выбранным backend.
- Designer backend получает private source transaction, а не project source tree. Source
`ConfigDumpInfo.xml` игнорируется; private CDFI/baseline/observation публикуются одной generation
только после successful pipeline.
- Отсутствие scoped `ib-state/v1` или missing/corrupt private CDFI означает full bootstrap;
legacy `workPath/hash-storages` не мигрируется.
- После успешного project stage, включая scoped `--source-set`, подготавливает
`tools.client_mcp.extension`, если оно настроено: `source` загружается как extension из
исходников, `.cfe` `artifact` загружается как extension с именем
`tools.client_mcp.extension.name`.
- Для source-backed `tools.client_mcp.extension` использует отдельное состояние change detection
под `workPath/hash-storages`: неизменённый source пропускает export/load, `--full-rebuild`
- Для source-backed `tools.client_mcp.extension` использует отдельное per-IB/per-source состояние
под `workPath/ib-state/v1`: неизменённый source пропускает export/load, `--full-rebuild`
принудительно обновляет расширение.
- `tools.client_mcp.extension` не является project `source-set`; `--source-set` выбирает только
project source-set.
Expand Down Expand Up @@ -254,8 +259,14 @@ v8-runner dump --mode <full|incremental|partial> [--source-set <NAME>] [--extens
потому что деградирует в incremental.
- `builder=DESIGNER` поддерживает true object-scoped partial.
- `builder=IBCMD` не умеет object-scoped partial; запрос деградирует в incremental с warning.
- `format=EDT` использует internal Designer snapshot под `workPath/designer/<sourceSetName>`,
затем импортирует его в EDT target и публикует результат атомарной заменой target каталога.
- Все режимы выполняются в private shadow. Missing baseline/private CDFI повышает
incremental/partial request до full shadow dump.
- B/S/D conflict, включая `B=absent, S=present, D=absent`, или TOCTOU mismatch публикует ноль
source files и не продвигает private generation.
- Conflict-free managed files публикуются через recoverable journal; exact generation и UUID
transaction token не позволяют принять чужую одноимённую generation за завершённый dump.
- Для `format=EDT` private Designer shadow импортируется в private EDT/configured shadow до той же
manifest publication; platform не пишет в project source или `workPath/designer/<sourceSetName>`.

### `convert`

Expand Down Expand Up @@ -376,7 +387,7 @@ v8-runner mcp serve http

Важные runtime директории:

- `workPath/hash-storages/`: persisted change-detection state.
- `workPath/ib-state/v1/`: opaque per-IB/per-source CDFI, baselines, observations and transaction journals; не редактируйте и не копируйте state между ИБ.
- `workPath/edt-workspace/`: общий EDT workspace для `init`.
- `workPath/convert/edt-workspace/`: отдельный EDT workspace для `convert`.
- `workPath/ibcmd-data/`: изолированный standalone-server data directory для IBCMD dump; это runtime state `v8-runner`, его можно удалить, когда нет активных CLI/MCP команд проекта.
Expand Down
12 changes: 8 additions & 4 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -257,13 +257,17 @@ tests:

Корень runtime state:

- `workPath/hash-storages`
- `workPath/ib-state/v1/<infobase-fingerprint>/<source-set>-<context-fingerprint>`
- `workPath/logs`
- `workPath/temp`
- `workPath/edt-workspace`
- `workPath/designer`

Если каталога нет, он создаётся автоматически.
Fingerprints являются opaque и зависят от secret-free identity ИБ и source context; их не
следует вычислять или редактировать вручную. Legacy `workPath/hash-storages` не мигрируется
и не переиспользуется. Первое обращение к scoped state выполняет full bootstrap, а не
интерпретирует отсутствующий snapshot как отсутствие изменений.

### `execution_timeout`

Expand Down Expand Up @@ -476,9 +480,9 @@ MCP endpoint и не гарантирует наличие Vanessa tools.
`tools.client_mcp.extension` не добавляется в `source-set` и не выбирается через `--source-set`.
`init` импортирует EDT `source` в workspace, `build` подготавливает расширение после project
source-set build, а `launch mcp` и `launch mcp va` расширение не устанавливают и не обновляют.
Для `source` build хранит отдельный snapshot под `workPath/hash-storages`: повторный запуск с
неизменёнными исходниками пропускает export/load, а `build --full-rebuild` принудительно
обновляет расширение.
Для `source` build хранит отдельный per-IB/per-source snapshot под `workPath/ib-state/v1`:
повторный запуск с неизменёнными исходниками пропускает export/load, а первое обращение или
`build --full-rebuild` выполняет full operation. Legacy snapshot не переиспользуется.

`v8-runner tools download client-mcp` может заполнить этот блок в `v8project.local.yaml`:
с `--sources` он указывает `source.path` на
Expand Down
Loading