feat(invocation-settings): require field-set transport

Author: Nick Franck

CHANGELOG.md

@@ -5,8 +5,9 @@
   body cap, the `/metadata` capability route, the request-scoped accessors, and `http_status_for`
   — the HTTP spelling of the
   library's normative `blame` → status rule. It sits on `utic-invocation-settings >=0.4.0`, which
-  owns the *settings contract* — including the field-atomic wire shape, independent sealed-field
-  resolution, and what an absent field is allowed to mean. That split is deliberate: the
+  owns the *settings contract* — including the field-set carrier as the only accepted sealed
+  `/invoke` shape, independent sealed-field resolution, and what an absent field is allowed to
+  mean. That split is deliberate: the
   absence rule is a security decision and belongs next to the crypto it governs, while request
   handling and route registration belong here, where a web framework is already a dependency.
   Nothing about the sealed-settings wire format is decided in this repository.
@@ -38,7 +39,7 @@
 * **Sealed settings consumption remains opt-in.** Pass
   `invoke_with_sealed_dag_node_settings=True` to `wrap_in_fastapi` / `generate_fast_api` (or
   `--sealed-dag-node-settings` on the CLI) only for a plugin that consumes per-invoke settings;
-  it advertises that the application accepts and acts on independently sealed settings fields.
+  it advertises that the application accepts and acts on the versioned field-set carrier.
   Transport support alone continues to advertise only `invocation_settings` and
   `invocation_context`. A
   plugin that serves a custom `/metadata` payload must register it via `add_metadata_route` (which

pyproject.toml

@@ -89,4 +89,4 @@ fail_under = 15
 
 [tool.uv.sources]
 # Temporary source pin until field-atomic utic-invocation-settings 0.4.0 is published.
-utic-invocation-settings = { git = "https://github.com/Unstructured-IO/utic-public-libs", subdirectory = "libs/utic-invocation-settings", rev = "733a15dd89a1696d3ac646e694f322ea06bc1eaf" }
+utic-invocation-settings = { git = "https://github.com/Unstructured-IO/utic-public-libs", subdirectory = "libs/utic-invocation-settings", rev = "814595faf94b424267b569c92211c093917988c4" }

test/api/test_invocation_envelope.py

@@ -15,7 +15,7 @@
 import pytest
 from fastapi import FastAPI, Request
 from fastapi.testclient import TestClient
-from utic_invocation_settings import Blame
+from utic_invocation_settings import FIELD_SET_FIELDS_KEY, FIELD_SET_FORMAT, Blame
 
 import unstructured_platform_plugins.invocation_settings as invocation_settings_transport
 from unstructured_platform_plugins.invocation_settings import (
@@ -414,8 +414,15 @@ def __init__(self, blame: Blame, secret: str = ""):
 class TestSettingsResolutionBoundary:
     """The library owns settings shape and crypto; this package owns delivery and HTTP mapping."""
 
-    def test_opaque_payload_is_delegated_and_final_mapping_is_bound(self, monkeypatch):
-        opaque_payload = {"contract-owned": {"content": "opaque-to-transport"}}
+    def test_field_set_payload_is_delegated_and_final_mapping_is_bound(self, monkeypatch):
+        opaque_payload = {
+            "dag_node_settings": {
+                "format": FIELD_SET_FORMAT,
+                FIELD_SET_FIELDS_KEY: {
+                    "api_key": {"format": "u10d.invocation-settings.v1", "opaque": "member"}
+                },
+            }
+        }
         resolved = {"api_key": "resolved-secret", "max_characters": 700}
         seen = []
 
@@ -433,6 +440,19 @@ def resolve(payload):
         assert seen == [opaque_payload]
         assert recorder.seen_settings == resolved
 
+    def test_empty_field_set_is_resolved_and_bound(self):
+        field_set_payload = {
+            "dag_node_settings": {
+                "format": FIELD_SET_FORMAT,
+                FIELD_SET_FIELDS_KEY: {},
+            }
+        }
+
+        recorder, response = _post_invoke({"invocation_settings": field_set_payload})
+
+        assert response.status_code == 200
+        assert recorder.seen_settings == {}
+
     def test_resolution_runs_off_the_event_loop(self, monkeypatch):
         resolver_threads = []
 

unstructured_platform_plugins/invocation_settings.py

@@ -1,8 +1,9 @@
 """Transport for the reserved `/invoke` fields: request dependency, `/metadata`, body cap.
 
-The *settings contract* — including the field-atomic wire shape, sealed-field resolution, and what
-an absent field is allowed to mean — lives in `utic_invocation_settings`, next to the crypto it
-governs; every decision about a settings payload is delegated there. The *identity contract* —
+The *settings contract* — including the only accepted sealed `/invoke` shape (the field-set
+carrier), sealed-field resolution, and what an absent field is allowed to mean — lives in
+`utic_invocation_settings`, next to the crypto it governs; every decision about a settings payload
+is delegated there. The *identity contract* —
 the `invocation_context` model — is
 `/invoke` protocol rather than settings security and lives in this package's
 `invocation_context` module. This module is the delivery mechanism for both: getting the payloads
@@ -127,7 +128,8 @@ def add_metadata_route(
     `invocation_settings` and `invocation_context` are transport capabilities: installing the
     dependency makes the host receive, resolve, and bind those fields. The sealed-settings
     capability is stronger: it tells the controller that the plugin handler consumes the resolved
-    field-atomic settings in place of boot-time state, so it remains an explicit opt-in.
+    field-atomic settings in place of boot-time state. The controller may therefore send the
+    versioned field-set carrier, so this remains an explicit opt-in.
 
     Last call wins: the payload lives on `app.state` and every call overwrites it, while the route
     is registered once. A host wrapper may register at app construction and a plugin can still