docs: make reference metadata optional

2026-08-12 02:22:01 +09:00
parent f28dbd7e42
commit 2bd297d84b
24 changed files with 127 additions and 95 deletions
@@ -12,7 +12,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
 - 기능별 reference model portfolio를 smoke, analytical, patch test, benchmark, regression, negative/invalid-input model로 구분한다.
 - `model.inp`가 I/O Definition Agent의 supported Abaqus keyword subset 안에 있는지 확인한다.
 - `reference/<model-id>/` artifact bundle 구조와 필수 파일을 정의한다.
- `metadata.json` provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 정의한다.
+- provenance, 단위, 좌표계, Abaqus version/source, output request, tolerance 정책을 기능별 Reference Model Contract에 정의한다. 선택 `metadata.json`이 존재하면 read-only로 inventory하고 계약과 대조한다.
 - Abaqus reference CSV 파일 요구사항을 정의한다.
 - requirement와 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, artifact status를 연결하는 Coverage Matrix를 작성한다.

@@ -53,12 +53,12 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반

 | model_id | category | purpose | status | required_artifacts |
 | --- | --- | --- | --- | --- |
-| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
-| <model-id> | analytical | <closed-form comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
-| <model-id> | patch test | <element consistency check> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
-| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
-| <model-id> | regression | <known defect guard> | draft | model.inp, metadata.json, required Abaqus reference CSV files |
-| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp, metadata.json |
+| <model-id> | smoke | <basic parser/solve path> | draft | model.inp, required Abaqus reference CSV files |
+| <model-id> | analytical | <closed-form comparison> | draft | model.inp, required Abaqus reference CSV files |
+| <model-id> | patch test | <element consistency check> | draft | model.inp, required Abaqus reference CSV files |
+| <model-id> | benchmark | <trusted benchmark comparison> | draft | model.inp, required Abaqus reference CSV files |
+| <model-id> | regression | <known defect guard> | draft | model.inp, required Abaqus reference CSV files |
+| <model-id> | negative/invalid-input | <unsupported keyword or invalid model diagnostic> | draft | model.inp |

 ## Model Record

@@ -90,7 +90,7 @@ Reference Model Agent는 FESA 기능 검증에 필요한 Abaqus `.inp` 기반
 reference/
  <model-id>/
    model.inp
-    metadata.json
+    metadata.json                     # optional
    <model-id>_displacements.csv
    <model-id>_reactions.csv
    <model-id>_internalforces.csv
@@ -100,7 +100,6 @@ reference/

 Required files:
 - `model.inp`: Abaqus input file for the reference model.
- `metadata.json`: provenance and model contract metadata.
 - `<model-id>_displacements.csv`: required when nodal displacement is a verification quantity.
 - `<model-id>_reactions.csv`: required when constrained DOF reactions or global equilibrium are verification quantities.
 - `<model-id>_internalforces.csv`: required when element internal force is a verification quantity.
@@ -108,12 +107,19 @@ Required files:
 - `README.md`: short description, generation notes, and limitations.

 Optional files:
+- `metadata.json`: optional machine-readable copy of reference metadata; inspect read-only and cross-check against the approved Reference Model Contract when present.
 - `<model-id>_strains.csv`: required when strain is part of the acceptance criteria.
 - `<model-id>_energy_or_residual.csv`: required when energy balance, residual, or convergence data is part of the acceptance criteria.
 - `<model-id>_<quantity>.csv`: feature-specific reference quantity when upstream contracts require it.
 - `notes.md`: manual review notes.

-## Metadata JSON Contract
+## Reference Metadata Contract
+
+The feature-specific Reference Model Contract is the required source of truth for every field
+below. A bundle does not need a `metadata.json` file. When the optional file exists, use this
+schema, inventory it read-only, and compare every overlapping field with the contract and stored
+artifacts. Absence is `absent-allowed`; a conflict is an upstream contract/provenance issue and
+must not be resolved by silently preferring either value.

 ```json
 {
@@ -180,10 +186,11 @@ Optional files:
 ## Artifact Acceptance Checklist
 - 모든 `must` requirement가 최소 하나의 `model_id`와 `compared_quantity`에 연결되어 있다.
 - `model.inp`가 기능별 supported Abaqus keyword subset을 벗어나지 않는다.
- `metadata.json`에 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 기록되어 있다.
+- Reference Model Contract에 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version과 artifact inventory가 기록되어 있다.
+- 선택 `metadata.json`의 부재는 허용되고, 존재하면 read-only inventory와 계약 일치 검사가 기록되어 있다.
 - 필요한 Abaqus reference CSV 파일이 존재하거나, 기능상 불필요한 quantity는 명확한 reason과 함께 제외되어 있다.
 - output request가 필요한 Abaqus reference CSV 물리량을 생성할 수 있도록 정의되어 있다.
- required Abaqus reference CSV 또는 metadata provenance가 없으면 status는 `needs-reference-artifacts`다.
+- required Abaqus reference CSV 또는 Reference Model Contract의 필수 provenance가 없으면 status는 `needs-reference-artifacts`다.
 - tolerance, source, units, coordinate system이 불명확하면 status는 `needs-user-decision`이다.

 ## Open Issues and Downstream Handoff
@@ -208,6 +215,7 @@ Optional files:
 - model data와 history data를 구분해야 한다.
 - output request와 required Abaqus reference CSV 사이의 연결이 명확해야 한다.
 - `reference/<model-id>/` 구조와 필수 artifact가 명시되어야 한다.
- `metadata.json`에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
+- Reference Model Contract에는 provenance, Abaqus version/source, units, coordinate system, tolerance, reference CSV schema version이 포함되어야 한다.
+- 선택 `metadata.json`은 없어도 되며, 존재할 때만 read-only로 참고하고 계약과 대조한다.
 - required Abaqus reference CSV가 없으면 완료 상태가 아니라 `needs-reference-artifacts` 상태로 둔다.
 - 모든 `must` requirement는 Coverage Matrix에서 model, compared quantity, FESA HDF5 dataset, reference CSV, tolerance, verification method로 추적되어야 한다.