refactor: close the remaining unguarded type assertions

Types the event-queue iterator's TReturn as undefined so the terminal
result needs no cast; declares the isError field the pi runtime reads by
duck-typing; binds socket to a local const in the daemon transport;
replaces the @ts-ignore on the optional sharp import with a non-literal
specifier so src/ still typechecks where sharp was not installed.

Adds src/util/guards.ts as the single home for narrowing over unknown —
isRecord plus scalar/array readers — and converts the two private
isObject copies in cdp/types.ts and daemon/protocol.ts along with every
inline `as Record<string, unknown>` in domains/js.ts and domains/render.ts.

Gives Accessibility.getFullAXTree a real result schema, closing the last
unvalidated CDP boundary: only nodeId is required, every object carries
additionalProperties, and each AX value stays Unknown, so the tree
decodes as a whole or fails as a whole rather than being filtered.

Guards the five tool-result `details` readers, the daemon attach
response, the persisted session state, the browser-namespace flag, and
the fs errno narrowing, each feeding an already-present failure path.

The daemon-transport socket binding is not a bug fix: send() runs
synchronously inside sendWithTimeout's promise executor, so socket cannot
be reassigned between the check and the write. It removes the assertion
and makes the write immune to a later refactor that adds an await.

Two assertions survive by design and are documented in the task report:
the never->unknown re-widening in util/tool.ts, which the type-erased
tool registry makes unavoidable, and the AsyncFunction constructor lookup
in domains/js.ts, which JavaScript exposes no typed binding for.

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

1 files changed, 59 insertions, 0 deletions

diff --git a/test/cdp/commands-test.ts b/test/cdp/commands-test.ts
index b316f68..ad1b057 100644
--- a/test/cdp/commands-test.ts
+++ b/test/cdp/commands-test.ts
@@ -43,3 +43,62 @@ describe("cdp command table", () => {
     assert.equal(r.success, false);
   });
 });
+
+describe("Accessibility.getFullAXTree schema", () => {
+  test("accepts a realistic Chrome AX node with unmodelled extra fields", () => {
+    const r = decodeResult("Accessibility.getFullAXTree", {
+      nodes: [
+        {
+          nodeId: "1",
+          ignored: false,
+          role: { type: "role", value: "RootWebArea" },
+          chromeRole: { type: "internalRole", value: 144 },
+          name: { type: "computedString", value: "Example", sources: [{ type: "relatedElement" }] },
+          properties: [
+            { name: "focusable", value: { type: "booleanOrUndefined", value: true } },
+            { name: "level", value: { type: "integer", value: 2 } },
+          ],
+          childIds: ["2", "3"],
+          backendDOMNodeId: 7,
+          frameId: "F1",
+        },
+        { nodeId: "2", parentId: "1", ignored: true, ignoredReasons: [{ name: "notRendered" }] },
+      ],
+    });
+    assert.equal(r.success, true);
+    if (r.success) {
+      assert.equal(r.data.nodes.length, 2);
+      assert.equal(r.data.nodes[0]?.role?.value, "RootWebArea");
+      assert.equal(r.data.nodes[0]?.backendDOMNodeId, 7);
+      assert.deepEqual(r.data.nodes[0]?.childIds, ["2", "3"]);
+    }
+  });
+
+  test("accepts an empty node list", () => {
+    const r = decodeResult("Accessibility.getFullAXTree", { nodes: [] });
+    assert.equal(r.success, true);
+  });
+
+  test("rejects a node whose nodeId is not a string", () => {
+    const r = decodeResult("Accessibility.getFullAXTree", { nodes: [{ nodeId: 5 }] });
+    assert.equal(r.success, false);
+    if (!r.success) assert.equal(r.error.kind, "invalid_response");
+  });
+
+  test("rejects childIds that are not strings", () => {
+    const r = decodeResult("Accessibility.getFullAXTree", { nodes: [{ nodeId: "1", childIds: [2] }] });
+    assert.equal(r.success, false);
+  });
+
+  test("rejects a missing nodes array", () => {
+    const r = decodeResult("Accessibility.getFullAXTree", {});
+    assert.equal(r.success, false);
+  });
+
+  test("keeps an AxValue's value untyped so any Chrome value type decodes", () => {
+    const r = decodeResult("Accessibility.getFullAXTree", {
+      nodes: [{ nodeId: "1", value: { type: "number", value: 42 } }, { nodeId: "2", name: { type: "x", value: null } }],
+    });
+    assert.equal(r.success, true);
+  });
+});