test: assertions for diff_surface (S2 Phase 1)

5 assertions: equal-set (no diff), surface-superset (missing), doc-
superset (stale). Sort-stable order verified.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

init.lua

@@ -57,6 +57,29 @@ Stuff.
         engine.test.equals(#no_api.documented, 0, "parse_readme_api: no API-section = empty")
     end
 
+    -- ===== diff_surface =====
+    do
+        -- Happy: surface == documented
+        local surface = { public = {"foo","bar"}, private = {"_x"} }
+        local readme  = { documented = {"foo","bar"} }
+        local diff = api.diff_surface(surface, readme)
+        engine.test.equals(#diff.missing_docs, 0, "diff_surface: equal -> no missing")
+        engine.test.equals(#diff.stale_docs, 0, "diff_surface: equal -> no stale")
+
+        -- Surface > Doc -> missing
+        local surface2 = { public = {"foo","bar","baz"}, private = {} }
+        local readme2  = { documented = {"foo"} }
+        local diff2 = api.diff_surface(surface2, readme2)
+        engine.test.equals(#diff2.missing_docs, 2, "diff_surface: 2 missing docs")
+        engine.test.assert(diff2.missing_docs[1] == "bar" or diff2.missing_docs[1] == "baz", "diff_surface: missing contains bar/baz")
+
+        -- Doc > Surface -> stale
+        local surface3 = { public = {"foo"}, private = {} }
+        local readme3  = { documented = {"foo","gone","also_gone"} }
+        local diff3 = api.diff_surface(surface3, readme3)
+        engine.test.equals(#diff3.stale_docs, 2, "diff_surface: 2 stale docs")
+    end
+
     engine.exit(engine.test.failures())
 end