File-series declaration validation and the add_file series-member guard were not ported (DID-matlab c80ba33) #69

Found while writing the tests for #68. Two guards that DID-matlab added in the same commit the Python file-series work claims to port — c80ba33, "Add file series to did.document: declaration, authoring, enumeration" — have no Python counterpart, and the bridge does not record their absence.

1. Document.__init__ does not validate file declarations

MATLAB's did.document constructor calls localValidateFileDeclarations (+did/document.m:67, body at :1524), which refuses four malformed declarations:

MATLAB's comment is explicit that this is not hygiene: "it is what makes the two mechanisms safe to coexist."

Python raises none of them:

from did.document import Document
from did.ido import IDO

props = {
    "base": {"id": IDO.unique_id(), "name": "test"},
    "files": {"file_list": ["plainfile.ext"], "file_series": ["chunkdata.bin"]},
}
Document(props).series_names()   # ['chunkdata.bin'] -- accepted

All four cases construct without complaint. A chunkdata.bin series with no chunkdata.bin in file_list has nowhere to put its manifest: add_file_series writes the manifest and calls add_file(name, ...), which appends a file_info entry regardless, so the document ends up with a manifest that is_in_file_list was never meant to serve.

2. Document.add_file does not refuse a series-member name

MATLAB (+did/document.m:496):

error('DID:Document:add_file:isSeriesMember', ...
    ['"%s" is a member of the file series "%s". Members are ' ...
     'added together by addFileSeries, which records them in ' ...
     'the series manifest.'], name, seriesStem);

Python accepts it:

d = Document("demoSeries")          # once demoSeries.json is ported; see #68
d.add_file("chunkdata.bin_5", "/tmp/a")
# -> file_info gains a 'chunkdata.bin_5' entry, no error

That is the divergence the guard exists to prevent. A member with its own file_info entry is invisible to the manifest, so series_members and series_count do not know about it while file_uids does — the two mechanisms then disagree about what the series contains, and which one answers depends on which code path a caller took.

Why the bridge did not catch this

+did/document.m's entry records matlab_last_sync_hash: 78583f6 with status: ported. c80ba33 is an ancestor of 78583f6, so the drift check is green: the bridge asserts this commit was reviewed. Nothing in the entry's decision_log mentions either guard, as a deviation or otherwise.

Related but separate, and noted here only so it is written down somewhere: the is_in_file_list member entry's decision_log says "Exact match. Synchronized 2026-03-16." Python's is_in_file_list is a file_info-only lookup returning (bool, info_dict, index); MATLAB's searches file_list, resolves NAME_12 to a NAME_# entry, falls back to series membership, and returns (b, msg, fI_index). The Python docstring calls the narrowing deliberate and gives a reason; the bridge entry claims the opposite. Whichever is right, they should not disagree — and the series fallback MATLAB added in c80ba33 is missing from the Python function either way.

Suggested fix

Port localValidateFileDeclarations as a private module function called from Document.__init__, and the member check in add_file. Python does not use MATLAB error identifiers for document errors, so ValueError with the same message content matches the existing convention (add_file_series already raises plain ValueError where MATLAB raises DID:Document:addFileSeries:notDeclared). Then update +did/document.m's decision_log to say so.

The tests for #68 will not encode the current behaviour on either point — a test that locks in a missing guard is worse than no test.