release: integrate dev into main for 0.4.0-alpha.1

AGENTS.md

@@ -228,14 +228,14 @@ let ``Validation fails for duplicate message IDs`` () =
 보고서 파일명은 다음 형식을 **반드시** 따른다:
 
 ```
-Reports/YYYYMMDD_HHMM_작업내용요약.md
+Reports/YYYYMMDD-HHMM_작업내용요약.md
 ```
 
 - `YYYYMMDD`: 작업 날짜 (예: 20260212)
 - `HHMM`: 작업 종료 시각 (24시간제, 예: 1430)
 - `작업내용요약`: 핵심 작업을 간결하게 (예: `Dbc_예외삼킴_수정`, `Core_테스트_구축`)
 
-예시: `Reports/20260212_1430_Dbc_예외삼킴_수정.md`
+예시: `Reports/20260212-1430_Dbc_예외삼킴_수정.md`
 
 ### 규칙 3: 보고서 필수 포함 항목
 
@@ -261,11 +261,21 @@ Reports/YYYYMMDD_HHMM_작업내용요약.md
 
 ### 규칙 6: 장기 실행 배치의 RUN_ID 규칙 (선택 적용)
 
-- 기본 규칙은 위의 `Reports/YYYYMMDD_HHMM_작업내용요약.md` 단일 보고서 방식이다
+- 기본 규칙은 위의 `Reports/YYYYMMDD-HHMM_작업내용요약.md` 단일 보고서 방식이다
 - 다만 작업이 여러 세션에 걸쳐 이어지는 **장기 실행 배치**라면, 필요 시 `RUN_ID`(`yyyymmdd-hhmm`, KST 기준)를 정하고 여러 보고서가 동일한 RUN_ID를 공유하도록 할 수 있다
 - 같은 미종료 배치를 이어서 수행하는 경우에는 새 RUN_ID를 임의로 만들지 말고 기존 RUN_ID를 재사용한다
 - 이 선택 규칙은 복구성과 추적성을 높이기 위한 보강 규칙이며, 현재 레포의 기본 단일 보고서 관행을 대체하지 않는다
 
+#### RUN_ID/파일명 운영 체크 (재발 방지)
+
+- 보고서 파일명 prefix(`YYYYMMDD-HHMM`)는 **해당 보고서의 RUN_ID**를 사용한다
+- 장기 실행 배치에서는 배치 시작 RUN_ID를 정한 뒤, 같은 배치의 후속 보고서도 같은 prefix를 사용한다
+- 배치 내 개별 단계 시각은 파일명 prefix가 아니라 본문 메타(예: `배치 내 단계 시각`)로만 기록한다
+- 기록 정정이 필요한 경우:
+  1. 원본 보고서 제목/본문보다 파일명 prefix 정합성을 우선 맞춘다
+  2. 본문에 `[정정 이력 - YYYY-MM-DD]`로 변경 근거를 남긴다
+  3. 기존 이력을 지우지 않고 patch-forward 방식으로 누적 기록한다
+
 ---
 
 > 이 규칙들은 프로젝트의 **추적 가능성(traceability)**과 **재현 가능성(reproducibility)**을 보장하기 위한 것입니다.

Plans/ORACLE_DECODER_STRATEGY.md

@@ -0,0 +1,103 @@
+# Oracle Reference Decoder Incompatibility Strategy
+
+## Problem Statement
+Three vendor DBC files from the testing corpus are currently excluded from oracle verification because the primary reference decoder, `cantools` (v41.2.1), fails to parse them. These files were classified as Exception 4 in `tests/oracle/CATEGORY_C_EXCEPTIONS.md`.
+
+**Affected Files and Errors:**
+1.  **hyundai_kia_generic.dbc**: Malformed `CM_` records at lines 1655-1657. `cantools` fails to handle unexpected formatting in comment records.
+2.  **toyota_2017_ref_pt.dbc**: 29-bit extended IDs rejected at line 387. `cantools` throws a "Standard frame id is more than 11 bits" error, suggesting it incorrectly treats extended frames as standard frames or fails to recognize the bit-31 extended flag.
+3.  **vw_meb.dbc**: 29-bit extended IDs rejected at line 2074. Same root cause as the Toyota DBC.
+
+Signal-CANdy successfully parses these files and generates valid C99 code, but the lack of a reference decoder prevents signal-level oracle verification for these specific targets.
+
+## Current State and Impact
+- **Exclusion Rate**: 3 significant vendor DBC files (Hyundai, Toyota, VW) are entirely excluded from the automated oracle pipeline.
+- **Verification Gap**: Changes to core logic affecting extended IDs or specific parsing edge cases cannot be cross-validated against a gold standard for these files.
+- **Classification**: These files are permanently assigned to `Category C` (reference\_decoder\_incompatible), which lowers the effective oracle coverage of the project.
+
+## Decision Context
+The project needs to decide whether to invest in a more robust or alternative reference decoder to achieve 100% oracle coverage or maintain the current status quo where `cantools` remains the sole, albeit limited, source of truth.
+
+## Option A: Maintain cantools-only + Category C policy (Status Quo)
+### Description
+Continue using `cantools` v41.2.1 as the exclusive reference decoder. Files that fail to parse are documented as Category C exceptions and excluded from oracle runs.
+
+### Evidence/Rationale
+`cantools` is the industry standard for Python-based CAN toolchains. Exception 4 documents that these failures are external to Signal-CANdy.
+
+### Pros
+- Zero additional implementation or maintenance effort.
+- Consistent environment (only one reference tool to manage).
+- Clear boundary: if the industry standard cannot parse it, exclusion is defensible.
+
+### Cons
+- Permanent verification gaps for high-value vendor DBCs.
+- Reduced confidence in generated code for extended ID messages (J1939/CAN FD style).
+
+### Effort: None
+### Recommendation Score: 6/10
+
+## Option B: Replace cantools with an alternative reference decoder (e.g., canmatrix)
+### Description
+Migrate the `run_oracle.py` and `engine.py` logic to use `canmatrix` or a similar library as the primary reference.
+
+### Evidence/Rationale
+Research indicates `canmatrix` is generally more lenient with DBC syntax anomalies (like the Hyundai `CM_` issue) and has a more flexible internal model for extended IDs.
+
+### Pros
+- Potential to resolve all 3 current Exception 4 cases.
+- `canmatrix` supports a wider range of formats (.arxml, .kcd), potentially expanding future test scope.
+
+### Cons
+- High migration effort: `run_oracle.py` is tightly coupled with the `cantools` API.
+- `canmatrix` is often cited as being slower and having a less "mature" high-level API than `cantools`.
+- Risk of introducing new Category C exceptions for files `cantools` handled but `canmatrix` might struggle with.
+
+### Effort: High
+### Recommendation Score: 3/10
+
+## Option C: Hybrid approach (cantools with fallback or canmatrix-based patching)
+### Description
+Keep `cantools` as the primary engine but implement a secondary path for Exception 4 files. This could involve using `canmatrix` just for the problematic files or implementing a pre-processing script to "fix" the DBCs before feeding them to `cantools`.
+
+### Evidence/Rationale
+The Toyota/VW errors ("Standard frame id is more than 11 bits") often stem from DBCs lacking the bit-31 flag that tools like `cantools` expect for extended IDs. A simple Python script could set these flags or clean malformed `CM_` records.
+
+### Pros
+- Resolves the verification gap for the 3 current files.
+- Retains the performance and stability of `cantools` for the bulk of the corpus.
+- Incremental effort.
+
+### Cons
+- Increases complexity of the test harness.
+- "Fixing" DBCs for the reference tool might mask genuine parsing bugs if not handled carefully.
+
+### Effort: Medium
+### Recommendation Score: 8/10
+
+## Recommended Path
+**Implement Option C (Hybrid/Pre-processing fallback).**
+
+Evidence suggests the current failures are solvable with targeted interventions:
+1.  **For Extended IDs (Toyota/VW)**: A pre-processing step can identify IDs > 0x7FF and ensure the extended bit is set (or use `canmatrix` to load and re-save the DBC in a "standardized" format).
+2.  **For Malformed CM_ (Hyundai)**: A simple regex-based "sanitizer" can fix the syntax anomalies before `cantools` reads the file.
+
+This approach provides the highest verification gain (resolving all 3 exclusions) with significantly less risk and effort than a full migration to a new decoder.
+
+## Decision Criteria
+- **Coverage**: Does it resolve the 3 excluded files?
+- **Stability**: Does it preserve existing verification for the rest of the corpus?
+- **Maintenance**: How much extra code is added to the test suite?
+- **Speed**: Does it impact CI run times?
+
+## Open Questions
+- Can a simple `sed`/`regex` fix the Hyundai `CM_` records without changing signal data?
+- Does `cantools` have an undocumented "lenient" mode that could be enabled via flags?
+- Is the extended ID issue in Toyota/VW DBCs a bug in the DBC files themselves (missing flag) or a strictness issue in `cantools`?
+
+## References
+- `tests/oracle/CATEGORY_C_EXCEPTIONS.md` Exception 4
+- `tests/oracle/ORACLE_RESULTS.md` Remaining Category C, Recommendation #4
+- `Plans/ROADMAP.md` Oracle decoder strategy item
+- [cantools Issue #301: Standard frame id is more than 11 bits](https://github.com/cantools/cantools/issues/301)
+- [canmatrix documentation: Lenient DBC parsing](https://canmatrix.readthedocs.io/en/latest/formats.html)

Plans/ROADMAP.md

@@ -12,13 +12,7 @@
 
 ## 현재 이관된 후속 항목
 
-### 1. valid 비트마스크 `>64` 신호 fallback 방식
-
-- 현 상태: `≤32 -> uint32_t`, `33–64 -> uint64_t`, `>64 -> UnsupportedFeature`
-- 근거: `Plans/Archive/ROADMAP_202602_202603_Closed.md` L-3a close-out 문구, `tests/oracle/CATEGORY_C_EXCEPTIONS.md` Exception 3
-- 후속 판단 과제: 배열 기반 valid 표현을 실제로 도입할지, 아니면 `>64` 미지원을 장기 정책으로 유지할지 결정
-
-### 2. Oracle reference decoder 비호환 DBC 대응 전략
+### 1. Oracle reference decoder 비호환 DBC 대응 전략
 
 - 현 상태: 일부 벤더 DBC는 `cantools` 파서 비호환으로 Category C 처리
 - 근거: `tests/oracle/CATEGORY_C_EXCEPTIONS.md` Exception 4, `tests/oracle/ORACLE_RESULTS.md`
@@ -27,5 +21,5 @@
 ## 다음 세션 진입점
 
 1. 최신 close-out / verification 보고서를 먼저 확인한다.
-2. 위 두 항목 중 실제 제품 우선순위가 생긴 것만 새 세대 계획으로 승격한다.
+2. 위 항목의 실제 제품 우선순위가 생기면 새 세대 계획으로 승격한다.
 3. 새 계획을 시작할 때는 archive 문서를 수정하지 않고, 이 문서 또는 `Plans/` 하위 successor roadmap에서 이어간다.

README.ko.md

@@ -24,8 +24,8 @@
 설치:
 
 ```pwsh
-dotnet add package SignalCandy.Core --version 0.3.2
-dotnet add package SignalCandy --version 0.3.2
+dotnet add package SignalCandy.Core --version 0.4.0-alpha.1
+dotnet add package SignalCandy --version 0.4.0-alpha.1
 ```
 
 ## ⚡ 빠른 시작 (5분)
@@ -457,7 +457,7 @@ make -C gen build
 참고
 - 분기 선택은 스위치 신호의 원시 정수값 기준입니다(일반 DBC 관례).
 - 멀티플렉스가 아닌 기반 신호는 항상 디코드/인코드됩니다.
-- 유효성 비트마스크 폭: 신호가 ≤32개인 메시지는 32비트 `valid` 필드(`uint32_t`)를 사용합니다; 33–64개 신호는 자동으로 64비트 필드(`uint64_t` + `1ULL` 시프트)를 사용합니다. 64개 초과 신호는 생성할 수 없으며 — 코드 생성은 `CodeGenError.UnsupportedFeature`를 보고합니다.
+- 유효성 비트마스크 폭: 신호가 ≤32개인 메시지는 32비트 `valid` 필드(`uint32_t`)를 사용합니다; 33–64개 신호는 자동으로 64비트 필드(`uint64_t` + `1ULL` 시프트)를 사용합니다; 65–1024개 신호는 바이트 배열 필드(`uint8_t valid[(N+7)/8]`)와 `sc_valid_set/clear/test()` 헬퍼 함수(`sc_utils.h`)를 사용합니다. 1024개 초과 다중화 신호 메시지는 지원되지 않습니다(코드 생성 시 `CodeGenError.UnsupportedFeature` 보고).
 
 valid와 mux_active 사용
 ```c
@@ -482,6 +482,23 @@ void handle_mux(const uint8_t data[8]) {
 }
 ```
 
+sc_valid_test 사용 (>64개 신호 — 바이트 배열 valid)
+```c
+#include "mux65_msg.h"
+#include "sc_utils.h"  /* sc_valid_test 헬퍼 — file_prefix가 sc_인 경우 sc_utils.h로 생성 */
+
+void handle_mux65(const uint8_t data[8]) {
+    MUX65_MSG_t m = {0};
+    if (MUX65_MSG_decode(&m, data, 8)) {
+        if (m.mux_active == MUX65_MSG_MUX_5) {
+            if (sc_valid_test(m.valid, MUX65_MSG_VALID_BRANCH_5)) {
+                /* m.Branch_5 사용 — >64개 신호 메시지의 인덱스 기반 valid 검사 */
+            }
+        }
+    }
+}
+```
+
 ### 값 테이블 (VAL_)
 
 `VAL_` 매핑이 있는 시그널은 C enum과 `to_string` 헬퍼가 생성됩니다:
@@ -606,7 +623,7 @@ void compare_state(int v) {
 - 실제 CRC/Counter 생성 검증은 명시적 `crc_counter:` YAML 메타데이터가 필요하며, 현재 지원 알고리즘은 CRC-8만 해당합니다.
 - 현재 `crc_counter_check: true`는 지원되지 않는 경로를 조용히 통과시키지 않도록 하는 fail-fast 가드레일로 동작합니다.
 - 클래식 CAN(최대 8바이트)과 CAN FD(최대 64바이트) 페이로드를 모두 지원합니다
- - 32개 초과의 다중화(mux) 시그널이 있는 메시지는 `uint64_t` valid 비트마스크를 자동 사용합니다. 64개 초과 시그널 메시지는 코드 생성 시 `CodeGenError.UnsupportedFeature`를 반환합니다
+- ≤32개 다중화(mux) 시그널 메시지는 32비트 `valid` 비트마스크(`uint32_t`)를 사용합니다; 33–64개 신호는 64비트(`uint64_t`)를 사용합니다; 65–1024개 신호는 바이트 배열(`uint8_t valid[(N+7)/8]`)과 `sc_utils.h`의 `sc_valid_set/clear/test()` 헬퍼를 사용합니다. 1024개 초과 다중화 신호 메시지는 지원되지 않습니다(`CodeGenError.UnsupportedFeature`).
 
 ## 디스패치 모드와 레지스트리 (nanopb와의 관련성)
 

README.md

@@ -24,8 +24,8 @@ This project generates portable C99 parser modules (headers/sources) from a `.db
 Install:
 
 ```pwsh
-dotnet add package SignalCandy.Core --version 0.3.2
-dotnet add package SignalCandy --version 0.3.2
+dotnet add package SignalCandy.Core --version 0.4.0-alpha.1
+dotnet add package SignalCandy --version 0.4.0-alpha.1
 ```
 
 ## ⚡ Quick Start (5 minutes)
@@ -326,7 +326,7 @@ make -C gen build
 Notes
 - Branch selection uses the raw integer value of the switch signal (typical DBC semantics).
 - Base (non-multiplexed) signals are always decoded/encoded.
- - Valid bitmask width: messages with ≤32 signals use a 32-bit `valid` field (`uint32_t`); messages with 33–64 signals automatically use a 64-bit field (`uint64_t` + `1ULL` shift). Messages with >64 signals cannot be generated — codegen reports `CodeGenError.UnsupportedFeature`.
+ - Valid bitmask width: messages with ≤32 signals use a 32-bit `valid` field (`uint32_t`); messages with 33–64 signals automatically use a 64-bit field (`uint64_t` + `1ULL` shift); messages with 65–1024 signals use a byte-array field (`uint8_t valid[(N+7)/8]`) with `sc_valid_set/clear/test()` helper functions from `sc_utils.h`. Messages with >1024 multiplexed signals are not supported (codegen reports `CodeGenError.UnsupportedFeature`).
 
 Using valid and mux_active
 ```c
@@ -351,6 +351,23 @@ void handle_mux(const uint8_t data[8]) {
 }
 ```
 
+Using sc_valid_test for >64 signals (byte-array valid)
+```c
+#include "mux65_msg.h"
+#include "sc_utils.h"  /* sc_valid_test helper — emitted as sc_utils.h when file_prefix is sc_ */
+
+void handle_mux65(const uint8_t data[8]) {
+    MUX65_MSG_t m = {0};
+    if (MUX65_MSG_decode(&m, data, 8)) {
+        if (m.mux_active == MUX65_MSG_MUX_5) {
+            if (sc_valid_test(m.valid, MUX65_MSG_VALID_BRANCH_5)) {
+                /* use m.Branch_5 — index-based valid check for >64 signal messages */
+            }
+        }
+    }
+}
+```
+
 ### Value tables (VAL_)
 
 Signals with `VAL_` mappings get C enums and to_string helpers:
@@ -680,7 +697,8 @@ Details can be reproduced via the stress suite and bulk runner in `scripts/bulk_
 - Generated CRC/Counter handling requires explicit `crc_counter:` YAML metadata; current supported algorithms are CRC-8 only.
 - When `crc_counter_check: true` is enabled without explicit metadata, code generation fails fast for inferred CRC/counter-like signals instead of silently accepting an unsupported path.
 - Supports both classic CAN (up to 8-byte) and CAN FD (up to 64-byte) payloads
-- Messages with >32 multiplexed signals automatically use a 64-bit `valid` bitmask (`uint64_t`). Messages with >64 multiplexed signals are not supported (code generation reports `CodeGenError.UnsupportedFeature`).
+- Messages with ≤32 multiplexed signals use a 32-bit `valid` bitmask (`uint32_t`); 33–64 signals use 64-bit (`uint64_t`); 65–1024 signals use a byte-array (`uint8_t valid[(N+7)/8]`) with `sc_valid_set/clear/test()` helpers from `sc_utils.h`. Messages with >1024 multiplexed signals are not supported (`CodeGenError.UnsupportedFeature`).
+
 
 ## Dispatch modes, registry, and relation to nanopb
 

Reports/20260316-0749_Codegen_ValidBitmask_RED_Tests.md

@@ -0,0 +1,54 @@
+# 작업 보고서: Codegen_ValidBitmask_RED_Tests
+
+**RUN_ID**: 20260316-0749  
+**배치 내 단계 시각(원본 파일명 기준)**: 20260316_0749
+
+## 📝 작업 요약
+
+- `tests/Signal.CANdy.Core.Tests/CodegenTests.fs`에 `>64` valid bitmask byte-array 기능용 RED 단계 테스트(T1–T6)를 추가/보강했다.
+- 기존 65-signal UnsupportedFeature 테스트를 성공 기대 테스트로 전환했고, 128/72/1024/1025/조건부 utils emission/비-mux 100-signal 시나리오를 추가해 현재 구현 한계를 명시적으로 깨뜨리도록 만들었다.
+- 요청된 로컬 커밋 `e0e788a` (`test(codegen): add failing tests for >64 valid byte-array`)를 생성했다.
+
+## 🛠 변경 상세
+
+- 수정 파일: `tests/Signal.CANdy.Core.Tests/CodegenTests.fs`
+  - 기존 `valid bitmask uses uint64_t for 64-signal mux message` 테스트에 `uint8_t` 배열이 나오지 않아야 함 / `1ULL` shift 사용 확인 assertion을 추가했다.
+  - 기존 65-signal mux valid bitmask 테스트를 `valid bitmask uses uint8_t byte array for 65-signal mux message`로 리팩터링했다.
+    - 실제 temp output directory 생성/정리 패턴으로 변경.
+    - header/source에 대해 `uint8_t valid[9]`, `VALID_BYTES`, plain index macro, `sc_utils.h`, `memset`, `sc_valid_set` 기반 동작을 기대하도록 작성.
+  - 신규 테스트 추가:
+    - `valid bitmask uses uint8_t byte array for 128-signal mux message`
+    - `utils header emits sc_valid helpers only when a message has more than 64 mux signals`
+    - `codegen fails with UnsupportedFeature for 1025-signal mux message`
+    - `valid bitmask uses uint8_t byte array for 72-signal mux message`
+    - `valid bitmask uses uint8_t byte array for 1024-signal mux message`
+  - 기존 non-mux 다신호 테스트를 `non-mux message with 100 signals has no valid field`로 확장했다.
+- 추가 확인:
+  - `lsp_diagnostics` 기준 변경 파일 컴파일 진단 오류 없음.
+
+## ✅ 테스트 결과
+
+- 실행 명령: `dotnet test --configuration Release -v minimal --nologo`
+- 결과:
+  - 빌드/테스트 실행 자체는 성공적으로 시작되었고 테스트 프로젝트 컴파일 오류는 없었다.
+  - `Signal.CANdy.Core.Tests`에서 총 6개 실패, 124개 통과.
+  - 실패한 신규/변경 테스트:
+    - `valid bitmask uses uint8_t byte array for 65-signal mux message`
+    - `valid bitmask uses uint8_t byte array for 128-signal mux message`
+    - `utils header emits sc_valid helpers only when a message has more than 64 mux signals`
+    - `codegen fails with UnsupportedFeature for 1025-signal mux message`
+    - `valid bitmask uses uint8_t byte array for 72-signal mux message`
+    - `valid bitmask uses uint8_t byte array for 1024-signal mux message`
+  - 실패 원인 요약:
+    - 현재 구현이 `>64` mux valid bitmask를 여전히 `UnsupportedFeature`로 처리한다.
+    - 1025-signal guard 메시지도 새 기대치(`1024`)와 불일치한다.
+  - 이는 RED phase 기대 결과와 일치한다.
+- `Generator.Tests`: 27개 통과.
+
+## ⏭ 다음 계획
+
+- 활성 ROADMAP 항목: `Plans/ROADMAP.md`의 `1. valid 비트마스크 >64 신호 fallback 방식`.
+- 다음 세션에서는 byte-array 기반 valid 표현(`uint8_t valid[N]`, helper emission, set/clear/test 호출, upper bound 정책)을 `src/Signal.CANdy.Core/Codegen.fs` 및 관련 템플릿에 구현하는 GREEN phase 작업이 필요하다.
+- 선행 조건:
+  - 이번 RED 테스트 기대치를 구현 설계와 정렬할 것.
+  - 현재 작업에서 완료된 ROADMAP 체크박스는 없음.