[verified] Document broker renew/status response contracts

2026-10-12 05:20:11 +00:00
parent b270c2ce30
commit 7b4b5e72f3
3 changed files with 112 additions and 0 deletions
@@ -84,6 +84,69 @@ class ManagedLockBrokerTests(unittest.TestCase):
        finally:
            os.close(parent_fd)

+    def test_operation_specific_broker_response_documentation(self):
+        import ast
+        harness = Path(__file__).parents[2]
+        operations = (harness / "operations/repository-cache.md").read_text()
+        reference = (harness / "agents/review/skills/gitea-code-review/references/native-review.md").read_text()
+        self.assertIn("### Operation-specific broker responses", operations)
+        contract = operations.split("### Operation-specific broker responses", 1)[1].split("### Canonical command templates", 1)[0]
+        for field in ("status", "deadline", "repository_held", "root", "owner", "repository", "issue", "role", "pid"):
+            self.assertIn(f"`{field}`", contract)
+        self.assertIn("request_handle(handle_path, action, ttl=None)", contract)
+        self.assertIn("### Broker response preflight before publication", reference)
+        section = reference.split("### Broker response preflight before publication", 1)[1].split("## Live integration", 1)[0]
+        recipe = section.split("```python\n", 1)[1].split("```", 1)[0]
+        ast.parse(recipe)
+        self.assertIn('broker.request_handle(broker_handle, "renew", ttl=ttl_seconds)', recipe)
+        self.assertIn('broker.request_handle(broker_handle, "status")', recipe)
+        self.assertIn('"error" in renewed', recipe)
+        self.assertIn('"error" in status', recipe)
+        self.assertIn('status.get("repository_held")', recipe)
+        self.assertNotIn('renewed["repository_held"]', recipe)
+        self.assertIn('lease.check(plan)', recipe)
+
+    def test_status_and_renew_have_distinct_success_and_error_shapes(self):
+        with tempfile.TemporaryDirectory() as d:
+            root = Path(d)
+            proc, handle, sock = self.start(root, ttl=30, role="gitea-review-agent")
+            status_keys = {"status", "deadline", "repository_held", "root", "owner", "repository", "issue", "role", "pid"}
+            try:
+                for held in (False, True):
+                    with self.subTest(repository_held=held):
+                        if held:
+                            self.assertEqual(broker.request_handle(handle, "acquire_repository"), {"status": "repository-held"})
+                        renewed = broker.request_handle(handle, "renew", ttl=30)
+                        self.assertEqual(set(renewed), {"status", "deadline"})
+                        self.assertEqual(renewed["status"], "repository-held" if held else "held")
+                        self.assertIs(type(renewed["deadline"]), float)
+                        self.assertGreater(renewed["deadline"], time.monotonic())
+                        with self.assertRaises(KeyError):
+                            renewed["repository_held"]
+                        status = broker.request_handle(handle, "status")
+                        self.assertEqual(set(status), status_keys)
+                        self.assertIs(status["repository_held"], held)
+                        self.assertEqual(status["status"], renewed["status"])
+                        self.assertEqual(status["deadline"], renewed["deadline"])
+                        self.assertEqual({key: status[key] for key in ("root", "owner", "repository", "issue", "role", "pid")},
+                                         {"root": str(root), "owner": "alice", "repository": "ledger", "issue": 7,
+                                          "role": "gitea-review-agent", "pid": proc.pid})
+                        rejected = broker.request_handle(handle, "renew", ttl=0)
+                        self.assertEqual(rejected, {"error": "invalid ttl_seconds"})
+                        unchanged = broker.request_handle(handle, "status")
+                        self.assertEqual(unchanged, status)
+            finally:
+                try:
+                    if proc.poll() is None:
+                        self.assertEqual(broker.request_handle(handle, "release"), {"status": "released"})
+                        self.assertEqual(proc.wait(timeout=3), 0)
+                finally:
+                    if proc.poll() is None:
+                        proc.kill(); proc.wait(timeout=3)
+                    proc.stdout.close(); proc.stderr.close()
+            self.assertFalse(sock.exists())
+            self.assertTrue(probe_free(root / "repositories/alice/ledger/locks/issue-7.lock"))
+
    def test_constructor_rejects_lexical_root_and_handle_aliases(self):
        with tempfile.TemporaryDirectory() as d:
            root = Path(d); ensure_cache(root)