[danyill]

What this pull request does

Adds one document: docs/proposals/0001-public-check-api.md. No code changes.

The document proposes a public check API for scl-lib: a family of check* functions that answer "can this operation be done, and if not, why". It also proposes one error model, one reason vocabulary and one policy for limits that a file does not declare.

Why

Issue #109 asks how the library should handle a function that fails. Today a caller gets null or [] and cannot tell why. Four element families have a canAdd* check that is not exported, and two public checks return a bare boolean.

The proposal answers the questions in #109:

• an expected refusal is returned, not thrown
• a caller error throws SclError, with the same vocabulary
• the library contains no user text and no translations
• one set of reason codes serves all element families and a future document check

Evidence

The design rests on a study of 716 real SCL files (120 sampled plus the four largest). Section 2.1 gives the results and Appendix B gives the method.

Three findings shaped the design:

1. 83 of 676 IEDs have no Services element, and 58 of 120 files use a service that they do not declare. A strict default blocks edits in those files.
2. ConfReportControl@max counts control blocks, not RptEnabled@max instances. The current counting rule refuses 72 scopes in 24 of 120 files; the element rule refuses 6 in 2.
3. Real files contain reference faults (dangling lnType, datSet, iedName). The library must report them and must not use them to refuse an unrelated edit.

How to review

Section 13.2 has 15 decisions. Each gives the options and our preferred answer. Reply with the decision number and the letter, for example D5: B, or comment on any line of the diff.

The option letters are not a ranking. In most decisions the preferred answer is listed first.

Scope of this pull request

• Design only. No dependency is added.
• npm test is unaffected: the change contains no TypeScript and no test.
• Merging this pull request closes Error handling in functions #109. Implementation follows in later pull requests, one for each element family.

Changes

• docs/proposals/0001-public-check-api.md (new)

[danyill]

We might never merge this but we could at least use it to comment/discuss