I’ve added the next part of Potbot’s tool system: checked contracts that describe what a tool accepts, what it returns, and which installed implementation will handle the call.
A search is a small example. It receives one typed query and returns one typed result. Those values carry their exact schema identities. Another operation can check the result and round-trip it into a stable JSON representation. An unknown Type, a changed schema or a missing required field stops the call.
The new contracts cover six records: the tool description, its capability, its implementation, its workspace installation, an invocation and the resulting evidence. They build on SYN’s existing Types and property system. Required properties are inherited, defaults stay visible, and optional properties remain optional.
I’ve implemented three Cogs to exercise this: a bounded search over a host-supplied corpus, a contract validator and a unit converter. Each has one registered input Type and one registered output Type. Each records its own start, actual progress and completion through Potbot’s existing work ledger.
The unit conversion makes a useful failure visible. The fixture converts 1,250 milliseconds into 1.250 seconds while retaining the original source hash and character spans. It carries the unit, precision and allowed tolerance explicitly. Asking for a result that loses more precision than allowed produces a failure. Ambiguous dates, unknown units and an unexpected locale are rejected too.
Where rounding is permitted, the output records the amount lost. A changed schema can be checked conservatively for new optional fields, but it cannot silently replace the schema already pinned to an active call. Changed required fields or existing constraints need a new versioned contract.
A tool description still needs an installed handler and permission to run. The binding check compares its handler reference, revision, hash and exact input/output schemas with the installed Cog. The controller checks admission again immediately before dispatch. A revoked grant, a direct handler call or failed work monitoring blocks the operation.
The end-to-end acceptance test imports the real SYN snapshot, persists the inherited property contracts, invokes the Cogs, and reads the stored output and statistics back through fresh services and the REST and WebSocket APIs. It also checks that another workspace cannot read those records. Wall time and the controller’s CPU interval are measured; target memory, device usage and costs remain unavailable where they haven’t been observed.
There are shared records for device, profiler and debugger sessions too, including exact target, process and source identities. Registering those records doesn’t establish a working phone connection or hardware probe. Python remains the first separately tested debugger backend. Signed provenance and live discovery have their own later stages.
The code, tests and recorded example are in the Potbot 0.5.0.dev5 source preview and canonical contract guide. This follows the earlier source inventory and Python debugger work.
Leave a Reply