Bound model-visible adapter metadata #143

Merged

lost-rob0t merged 8 commits from agent/107-bound-adapter-metadata into main

2026-08-21 05:01:43 +00:00

lost-rob0t commented

2026-08-21 04:53:53 +00:00

(Migrated from github.com)

Closes #107.

Problem

Trusted external-context adapters may return model-visible metadata during context_register_adapter/4. The core previously required only a ground dict, so a buggy or malicious trusted adapter could publish an arbitrarily large descriptor outside the normal context output ceiling.

Change

reuse the already-validated max_bytes registration option as the complete adapter-metadata ceiling;
measure the complete model-visible context_metadata{...} descriptor with the same serialized-term UTF-8 accounting used by model-visible context term output;
reject oversized metadata before context-record/handle publication instead of truncating it;
return structured adapter_metadata_too_large errors containing observed bytes and max_bytes;
preserve the ordinary default ceiling (16 KiB) and existing small metadata behavior;
document the registration-time boundary.

TDD

The regression test was committed before the implementation. Under the same max_bytes(512) ceiling it first proves ordinary adapter metadata registers successfully, deletes that handle, then supplies a 4 KiB adapter-controlled payload and requires a structured rejection. It immediately unregisters the adapter after the rejection; successful unregister proves no context handle leaked from the failed registration.

The existing suite continues to cover that ordinary context source data cannot install executable adapter callbacks.

Validation

This runtime does not have SWI-Prolog installed locally, so the exact-head GitHub Actions gate is authoritative. The PR remains unmerged until those checks are observed green.

Closes #107. ## Problem Trusted external-context adapters may return model-visible metadata during `context_register_adapter/4`. The core previously required only a ground dict, so a buggy or malicious trusted adapter could publish an arbitrarily large descriptor outside the normal context output ceiling. ## Change - reuse the already-validated `max_bytes` registration option as the complete adapter-metadata ceiling; - measure the complete model-visible `context_metadata{...}` descriptor with the same serialized-term UTF-8 accounting used by model-visible context term output; - reject oversized metadata before context-record/handle publication instead of truncating it; - return structured `adapter_metadata_too_large` errors containing observed `bytes` and `max_bytes`; - preserve the ordinary default ceiling (16 KiB) and existing small metadata behavior; - document the registration-time boundary. ## TDD The regression test was committed before the implementation. Under the same `max_bytes(512)` ceiling it first proves ordinary adapter metadata registers successfully, deletes that handle, then supplies a 4 KiB adapter-controlled payload and requires a structured rejection. It immediately unregisters the adapter after the rejection; successful unregister proves no context handle leaked from the failed registration. The existing suite continues to cover that ordinary context source data cannot install executable adapter callbacks. ## Validation This runtime does not have SWI-Prolog installed locally, so the exact-head GitHub Actions gate is authoritative. The PR remains unmerged until those checks are observed green.