Merge branch 'stroland02/m1-static-gate'

# Conflicts:
#	tests/test_decode_handlers.py

Author: stroland02

docs/superpowers/reports/2026-07-29-directory-skips-recorded.md

@@ -1574,9 +1574,9 @@ def intake(args: argparse.Namespace) -> int:
     # The directory is a document somebody fetched, parsed here rather than downloaded: this
     # command reports what the deployment already knows, and a fetch inside it would make a
     # report of what is on disk quietly online.
-    directory = (
+    directory, directory_unreadable = (
         parse_directory(json.loads(Path(args.registry_directory).read_text(encoding="utf-8")))
-        if args.registry_directory else []
+        if args.registry_directory else ([], ())
     )
     registry_apis = (
         read_registry_apis(Path(args.registry_evidence)) if args.registry_evidence else {}
@@ -1585,6 +1585,7 @@ def intake(args: argparse.Namespace) -> int:
         Path(args.repo),
         generator_manifests=evidence,
         registry_entries=directory,
+        registry_unreadable=directory_unreadable,
         registry_apis=registry_apis,
         registry_moved_since=args.registry_moved_since,
     )
@@ -1609,8 +1610,10 @@ def intake(args: argparse.Namespace) -> int:
 
     for problem in report.unreadable:
         # To stderr, and never silently. A manifest that would not parse is not a repository
-        # with no dependencies, and reported as one it reads as a clean scan of an empty project.
-        print(f"unreadable manifest: {problem}", file=sys.stderr)
+        # with no dependencies, and reported as one it reads as a clean scan of an empty project;
+        # a declined catalogue entry is the same narrowing arriving from a different file. The
+        # prefix names neither, because each problem already names its own source.
+        print(f"unreadable: {problem}", file=sys.stderr)
     return 0
 
 

src/sync/cli.py

@@ -158,6 +158,13 @@ class IntakeReport:
     `unreadable` is not an error channel. A manifest that does not parse is a fact a customer
     needs, because a repository whose manifest is unreadable is not a repository with no
     dependencies -- and reported as the latter it reads as a clean scan of an empty project.
+
+    It holds every input that would not read, not only the manifests. The vendor catalogue is one
+    of them: a directory entry `parse_directory` declined is a package this report will call
+    not-watchable for a reason that has nothing to do with the package, which is the same narrowing
+    under a different name. They share the key rather than getting one each -- the three manifest
+    readers already share it and tell themselves apart by the prefix on each string, so a reader
+    needs one rule for this fact and not one per input.
     """
 
     assessments: tuple[Assessment, ...]
@@ -451,6 +458,7 @@ def assess_repository(
     bindings: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
     configured_repos: Mapping[str, str] | None = None,
     registry_entries: Sequence[RegistryEntry] = (),
+    registry_unreadable: Sequence[str] = (),
     registry_apis: Mapping[str, str] | None = None,
     registry_moved_since: str | None = None,
 ) -> IntakeReport:
@@ -460,6 +468,12 @@ def assess_repository(
     actually has. That is what keeps the classification testable against committed fixtures and
     keeps the network out: `generator_manifests` is evidence somebody gathered, not something
     this function goes and looks up.
+
+    `registry_unreadable` is the other half of what `parse_directory` returns, and it arrives with
+    the entries because a report built from a catalogue that partly would not read has to say so.
+    It defaults empty beside `registry_entries` rather than being required: a deployment that
+    passed no directory has no directory faults, so empty is the truth there rather than a silent
+    claim.
     """
     declared, unreadable = read_declared_dependencies(Path(root))
     resolved_bindings = vendor_sdk_bindings() if bindings is None else bindings
@@ -474,4 +488,6 @@ def assess_repository(
         _classify(dependency, packages[dependency.ecosystem], resolved_repos, evidence, registry)
         for dependency in declared
     )
-    return IntakeReport(assessments=assessments, unreadable=unreadable)
+    return IntakeReport(
+        assessments=assessments, unreadable=(*unreadable, *registry_unreadable)
+    )

src/sync/signals/intake.py

@@ -65,28 +65,76 @@ class RegistryEntry:
     versions: dict[str, RegistryVersion]
 
 
-def parse_directory(document: dict[str, Any]) -> list[RegistryEntry]:
-    """Every usable entry in a directory document.
+# The source every skip is attributed to, in the position `sync.signals.intake` puts a manifest's
+# filename. One `unreadable` list holds faults from several inputs, so each string has to say
+# which one it came from before it says what was wrong with it.
+_SOURCE = "registry directory"
+
+
+def _timestamp(detail: dict[str, Any]) -> str | None:
+    """When this version last moved, preferring `updated` and falling back on `added`.
+
+    The fallback triggers on a value this tier cannot use rather than on a falsy one. A numeric
+    `updated` is truthy, so `detail.get("updated") or detail.get("added")` let it win and then
+    failed the string check, skipping a version whose `added` was perfectly readable. Usable means
+    a non-empty string: `versions_after` compares timestamps as strings and `""` compares less
+    than every real one, so an empty value admitted here would be reported as a version that
+    never moves.
+    """
+    for key in ("updated", "added"):
+        value = detail.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def parse_directory(document: dict[str, Any]) -> tuple[list[RegistryEntry], tuple[str, ...]]:
+    """Every usable entry in a directory document, and every entry or version it declined.
 
     A public directory is untrusted input and it is large. A malformed entry is skipped rather
     than raised on: one bad row must not cost the other thousands, and an entry with no versions
     has nothing to say about what changed, so skipping loses nothing that could have been used.
+
+    What it does lose is the vendor. A skipped entry is one Sync will never offer to watch, and
+    reported as an absence it is indistinguishable from a directory that never listed it -- so the
+    second half of the return says what was declined and why, in the key and shape
+    `IntakeReport.unreadable` established and `ReachabilityRanking` already carries. Empty rather
+    than absent on a clean document, because a caller cannot otherwise tell a clean read from a
+    parser that never recorded a fault.
+
+    An entry that kept none of its versions is recorded too, and is deliberately not a fifth
+    cause: it follows from the version-scoped skips already recorded above it. It is there because
+    it is the only record that says the vendor is gone rather than one of its versions.
     """
     entries: list[RegistryEntry] = []
+    unreadable: list[str] = []
     for api_id, body in document.items():
         if not isinstance(body, dict):
+            unreadable.append(f"{_SOURCE}: '{api_id}' is not an object")
             continue
         raw_versions = body.get("versions")
         if not isinstance(raw_versions, dict) or not raw_versions:
+            unreadable.append(f"{_SOURCE}: '{api_id}' declares no versions object")
             continue
 
         versions: dict[str, RegistryVersion] = {}
         for version, detail in raw_versions.items():
             if not isinstance(detail, dict):
+                unreadable.append(f"{_SOURCE}: '{api_id}' version '{version}' is not an object")
                 continue
             spec_url = detail.get("swaggerUrl")
-            updated = detail.get("updated") or detail.get("added")
-            if not isinstance(spec_url, str) or not isinstance(updated, str):
+            if not isinstance(spec_url, str):
+                unreadable.append(
+                    f"{_SOURCE}: '{api_id}' version '{version}' declares no swaggerUrl string, "
+                    f"so there is nothing to download"
+                )
+                continue
+            updated = _timestamp(detail)
+            if updated is None:
+                unreadable.append(
+                    f"{_SOURCE}: '{api_id}' version '{version}' declares no usable updated or "
+                    f"added timestamp, so nothing can compare it against a watermark"
+                )
                 continue
             versions[version] = RegistryVersion(
                 version=version,
@@ -96,6 +144,10 @@ def parse_directory(document: dict[str, Any]) -> list[RegistryEntry]:
             )
 
         if not versions:
+            unreadable.append(
+                f"{_SOURCE}: '{api_id}' is not discoverable -- none of the "
+                f"{len(raw_versions)} version(s) it declares could be read, each recorded above"
+            )
             continue
         preferred = body.get("preferred")
         entries.append(
@@ -105,7 +157,7 @@ def parse_directory(document: dict[str, Any]) -> list[RegistryEntry]:
                 versions=versions,
             )
         )
-    return entries
+    return entries, tuple(unreadable)
 
 
 def versions_after(entries: list[RegistryEntry], watermark: str) -> list[tuple[RegistryEntry, str]]:

src/sync/signals/registry_tier/directory.py

@@ -246,7 +246,9 @@ def test_intake_ranked_puts_an_unreadable_manifest_in_the_artifact_and_not_only_
     payload = json.loads(captured.out)
     assert payload["rows"] == []
     assert any("package.json" in problem for problem in payload["unreadable"])
-    assert "unreadable manifest:" in captured.err
+    # The prefix names no source, because the list holds faults from several and each string
+    # already names its own -- `package.json` here, a declined catalogue entry elsewhere.
+    assert "unreadable: package.json" in captured.err
 
 
 # --- sync benchmark scores --------------------------------------------------------------

tests/test_cli_wiring_reachability.py

@@ -421,9 +421,9 @@ def _drive_ts_manifest(root: Path) -> None:
     "sync/remediate/property_omit.py:93": _drive_property_omit,
     "sync/remediate/tiered.py:174": _drive_tiered_literal,
     "sync/signals/feed/consumer.py:72": _drive_feed,
-    "sync/signals/intake.py:288": _drive_intake_npm,
-    "sync/signals/intake.py:324": _drive_intake_pyproject,
-    "sync/signals/intake.py:335": _drive_intake_requirements,
+    "sync/signals/intake.py:295": _drive_intake_npm,
+    "sync/signals/intake.py:331": _drive_intake_pyproject,
+    "sync/signals/intake.py:342": _drive_intake_requirements,
 }