From 331815d4583b62565229f04f05b90f403a357b36 Mon Sep 17 00:00:00 2001 From: Emil <65846814+emil28092005@users.noreply.github.com> Date: Thu, 24 Sep 2026 04:04:23 +0300 Subject: [PATCH] Describe staged source verification boundaries accurately --- docs/ARCHITECTURE.md | 8 ++++++-- docs/IMPLEMENTATION.md | 10 ++++++---- docs/manual/editor/export.md | 7 ++++--- docs/manual/scripting/lua.md | 2 +- docs/validation/p1-iteration-2026-09-24/README.md | 8 +++++++- include/faset/editor/build_cache.hpp | 4 ++-- 6 files changed, 26 insertions(+), 13 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 6ab285d..55726b0 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -114,13 +114,17 @@ Development и release Player содержат runtime, выбранные иг ## 10. P1 — проверяемая итерация gameplay Для native-сборки источником истины остаются CMake/Ninja и их dependency graph. -BuildService снимает неизменяемый snapshot `Scripts`, отделяет Debug от Release и +BuildService сохраняет проверяемую копию `Scripts` по хешу содержимого, +отделяет Debug от Release и запоминает версионированный fingerprint рецепта, исходников, Lua-деклараций, toolchain, шейдерных и runtime-входов. Повторное использование schema/package разрешено лишь после проверки полного manifest и схемы; испорченная или устаревшая генерация не выдаётся за cache hit. Переключение указателя на успешную генерацию атомарно; сбой сборки оставляет предыдущую доступной, но Inspector помечает -метаданные устаревшими. Экспорт отдельно проверяет asset generations. +метаданные устаревшими. Исходный каталог и копия повторно хешируются после native +build и перед повторным использованием кэша или публикацией. Это обнаруживает сохранившееся изменение; +запись и восстановление прежних байтов другим процессом того же пользователя во +время чтения компилятором не исключены. Экспорт отдельно проверяет asset generations. Структурированные сообщения компилятора/Lua дополняют сырой лог. Для исходников проекта Editor и MCP вызывают один `faset_source_open` с относительным путём и diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md index d386fb3..c0172f3 100644 --- a/docs/IMPLEMENTATION.md +++ b/docs/IMPLEMENTATION.md @@ -469,18 +469,20 @@ GPU coverage remain untested. ## Post-MVP checkpoint — P1 gameplay iteration -P1 adds a complete-input native build stamp and an immutable `Scripts` snapshot. +P1 adds a complete-input native build stamp and a content-addressed `Scripts` copy. The package key binds configuration, recipe, source, Lua declaration, toolchain, shader and runtime artifacts. A second unchanged build reuses a verified schema and package generation without invoking SchemaExporter; CMake/Ninja still verify the native graph. Malformed/corrupt generations, modified headers/tools and -source races cannot publish a false hit. Failed jobs preserve the previous -successful pointer, while Inspector metadata becomes stale. +detected source mismatches cannot publish a false hit. The live tree and staged +copy are rehashed after native build and before reuse/publication; a same-user +write-and-restore during compiler reads remains outside this check. Failed jobs +preserve the previous successful pointer, while Inspector metadata becomes stale. Compiler and Lua output now produce bounded structured Console diagnostics with raw logs retained. Source opening accepts only project `Scripts` files and passes literal file/line/column arguments to the configured external editor. A real -compile failure revealed that compiler paths pointed to the immutable snapshot; +compile failure revealed that compiler paths pointed to the staged copy; `d7a7a7c` maps only the verified snapshot subtree back to project-relative source. The same correction retains a later actionable error after 250 unrelated warnings. Four runnable C++/Lua × 2D/3D starters are available in launcher and diff --git a/docs/manual/editor/export.md b/docs/manual/editor/export.md index 8c05f25..440b7e7 100644 --- a/docs/manual/editor/export.md +++ b/docs/manual/editor/export.md @@ -28,7 +28,7 @@ Player is observed by the Editor, which keeps its logs and authoring state. An unchanged second build still asks CMake/Ninja to verify their dependency graph. When the native outputs, gameplay sources, toolchain, shaders and runtime inputs match the validated package, **Jobs** reports `schema_cache_hit` and -`generation_reused` as true and returns the same immutable generation without a +`generation_reused` as true and returns the same verified generation without a second SchemaExporter run or package copy. A changed `.cpp`, header, Lua declaration, build recipe or relevant tool invalidates that reuse. A damaged cached package is not treated as a hit. The job also exposes elapsed phases and a build fingerprint; @@ -64,9 +64,10 @@ Development builds use **Debug**. Exports default to **Release** and use a separ CMake cache. The BuildService API also accepts `RelWithDebInfo` for exports. Exporting does not change the configuration of your development Player. -Each successful export creates an immutable directory under +Each successful export creates a versioned directory under `Exports/MyGame/generations/`. `current.json` points to the active -generation. Distribute the **whole generation directory**, not just the executable. +generation. The Editor leaves published generations untouched. Distribute the +**whole generation directory**, not just the executable. If building, cooking or verification fails, the previous pointer and package remain available. Cancelling a job does not delete earlier exports. diff --git a/docs/manual/scripting/lua.md b/docs/manual/scripting/lua.md index 3e8b00d..7c6d08f 100644 --- a/docs/manual/scripting/lua.md +++ b/docs/manual/scripting/lua.md @@ -36,7 +36,7 @@ Add explicit entry scripts to `project.faset.json`: This is a manifest fragment, not a complete project file. Each entry must return one `faset.behavior` table with a unique custom TypeId. All sources live beneath `Scripts` -and are captured as an immutable build/export snapshot. Paths must be project-relative; +and are copied into a content-verified build/export snapshot. Paths must be project-relative; symlinks and paths outside `Scripts` are rejected. Auxiliary modules do not need to appear in the entry list. diff --git a/docs/validation/p1-iteration-2026-09-24/README.md b/docs/validation/p1-iteration-2026-09-24/README.md index 6e5e2ea..6f6df26 100644 --- a/docs/validation/p1-iteration-2026-09-24/README.md +++ b/docs/validation/p1-iteration-2026-09-24/README.md @@ -45,7 +45,7 @@ The run also imported the small Blender bundle cold and cached in 49 and 52 ms, respectively; Editor process startup dominates that tiny asset sample, so those two values do not establish import-cache speedup. The raw [failed-build job](raw/build_failure-01-stdout.txt) exposed a navigation defect: -the compiler named the immutable source snapshot, and the original structured +the compiler named the staged source copy, and the original structured diagnostic omitted `file`. A later fix maps only the verified staged `Scripts` subtree to project-relative source. A [real failed-build replay](diagnostic-replay.json) with the corrected Editor returns `Scripts/Gameplay.cpp`, line 73, column 2. @@ -54,6 +54,12 @@ Windows drives; `build_schema_publication` verifies that an error after 250 third-party warnings survives the 200-row diagnostic limit. These are separate from this unmodified measurement. +Follow-up `54d1bae` rehashes both the live source and the staged copy after +native build and before reuse/publication. A fixture changes the staged C++ +header during schema export; the build fails and retains the last-good pointer. +The copy is content-verified at those boundaries, not sealed against a same-user +write-and-restore during compiler reads. + The [3,000-frame lifecycle profile](raw/cpp-3000-frame-lifecycle.json) completed with zero Vulkan validation errors. Maximum explicit Vulkan allocation was 15,787,008 bytes in both frames 101–200 and 2901–3000, a measured growth of zero; diff --git a/include/faset/editor/build_cache.hpp b/include/faset/editor/build_cache.hpp index 95e6a92..9c18668 100644 --- a/include/faset/editor/build_cache.hpp +++ b/include/faset/editor/build_cache.hpp @@ -23,8 +23,8 @@ BuildInputs capture_build_inputs(const BuildConfig& config, const scripting::Lua std::optional configured_cmake_value(const BuildConfig& config, std::string_view key); -// Copy a content-addressed, immutable Scripts tree for the native compiler. -// Returning the same path for equal source bytes preserves Ninja incrementality. +// Copy a content-addressed Scripts tree for the native compiler. BuildService +// rehashes it at phase boundaries; returning the same path preserves Ninja incrementality. std::filesystem::path stage_gameplay_sources(const BuildConfig& config, const BuildInputs& inputs, const scripting::LuaProject& lua,