docs(craft): state the partial-metadata contract on the file signal

An adapter that omits size or mtime for an unhashed file degrades change
detection to the field it did supply. The docstring says so and a test pins
the degradation, since no metadata-only signal can see a change in data it
was never given.

Author: nmgarza5

backend/onyx/server/features/build/artifact_classifier.py

@@ -117,7 +117,10 @@ def _is_visible(path: str) -> bool:
 
 def _file_signal(entry: OutputEntry) -> str | None:
     """Change signal for a file: its hash, or a size-and-mtime surrogate for
-    files past the hash ceiling, shaped so it can never read as a real sha."""
+    files past the hash ceiling, shaped so it can never read as a real sha.
+    The manifest carries fstat size and mtime for every file it lists. An
+    adapter omitting one degrades detection to the other field alone, which
+    still beats no signal, so partial metadata is accepted."""
     if entry.sha256 is not None:
         return entry.sha256
     if entry.size is None and entry.mtime_ns is None:

backend/tests/unit/onyx/server/features/craft/test_artifact_classifier.py

@@ -158,6 +158,14 @@ def top(entry: OutputEntry) -> str | None:
     assert top(base) != top(OutputEntry("big.bin", False, size=10, mtime_ns=2))
     assert top(OutputEntry("big.bin", False)) is None
 
+    # Partial metadata degrades to what is present, never to no signal.
+    assert top(OutputEntry("big.bin", False, size=10)) != top(
+        OutputEntry("big.bin", False, size=20)
+    )
+    assert top(OutputEntry("big.bin", False, mtime_ns=1)) != top(
+        OutputEntry("big.bin", False, mtime_ns=2)
+    )
+
     # The same surrogate drives the directory hash for nested unhashed files.
     def nested(entry: OutputEntry) -> str | None:
         return derive_artifacts([OutputEntry("d", True), entry])[0].content_hash