PAL.NET in Practice: Connecting Once, Then Expanding Without Rework

Note on scope. PAL.NET has been in operational use for over a year. This piece describes the developer experience and the design decisions behind it, and does not identify the environment it runs in.

Where integrations usually go wrong

A team is asked to get one dataset out of Palantir Foundry and into a .NET service. That is a day of work. The trouble starts at the second request, because the second request is never the same shape as the first. A different service, a different error body, a different pagination convention. By the fifth, the integration layer has become the least pleasant part of the codebase and the one person who understands it has moved teams.

PAL.NET exists to make the first connection cheap and the fifth one no more expensive than the first.

The first connection

The SDK arrives from an authenticated private NuGet feed, or as a licensed offline bundle where the environment has no route to a feed. A developer registers the capability groups the application needs, supplies platform credentials, and the licence entitlement check runs at startup. That check is fail-closed by design. An unlicensed build does not fall back to a degraded mode that someone discovers in production three weeks later.

From that point the application calls typed, async methods. Payloads are immutable records. Every operation takes a cancellation token, which matters more than it sounds: a long-running query against a large dataset is exactly the thing you need to be able to abandon cleanly when a request times out upstream.

Adding the second capability

This is the test that matters. The service that started by reading datasets now needs to run SQL queries, then to write into a media set, then to call a function, then to subscribe to a stream. In a hand-rolled client each of those is a fresh negotiation with the platform’s surface area.

With PAL.NET each one is an additional capability registration. Connectivity, datasets, filesystem, data health, streams, SQL queries, functions, orchestration, media sets, map rendering, models, the LLM proxy, AIP agents, admin, audit, checkpoints and the sensitive data scanner all follow the same conventions for authentication, errors and cancellation. The integration layer stops growing in complexity as the application grows in scope.

Modular registration also keeps the dependency surface honest. An application that does not touch map rendering does not carry it. In environments where every dependency has to be justified, that is a practical benefit rather than a tidiness argument.

Reaching the Ontology

Most of the value in a Foundry estate sits in the Ontology, and most of the pain in integrating with it comes from the fact that it is specific to the customer. PAL.NET treats it as a first-class surface rather than a special case bolted onto the platform client.

Where the model is known at build time, generated strongly typed C# contracts mean a renamed property or a changed link type surfaces as a compile error. Where the model is discovered at runtime, or where an application has to work against several tenants with different shapes, dynamic metadata-driven access covers it, including the specialised Ontology data access paths. Teams commonly need both, often in the same application, so the two share one runtime.

Surviving the upgrade

Expandability is not only about adding capability. It is about whether the thing you built last year still works after the platform moves. The API Compatibility Manifest states what a given SDK release supports, and release gates are tied to it. A team can therefore answer the question that is otherwise answered by trial and error: is this version safe to take?

For accredited and disconnected estates, where a deployment is a scheduled event rather than a continuous process, having that contract written down is the difference between a planned upgrade and an unplanned investigation.

Staying out of the way

PAL.NET targets under five milliseconds of SDK overhead at the 95th percentile for payloads up to 64 KiB, excluding network time. The reason for stating it as a target rather than a claim is that an access layer which adds measurable latency gets worked around, and a worked-around SDK is worse than no SDK at all.

Internally the SDK reuses AIC.Foundry and AIC.Foundation, the same libraries behind our other .NET work. That is deliberate: it means the behaviour of configuration, logging and error handling is already familiar to anyone who has worked with the rest of the estate.

What to take from it

The useful question to ask of any platform SDK is not how quickly you can make the first call. It is what the tenth capability and the second major platform version cost you. PAL.NET is designed around those two moments: consistent conventions so breadth is cheap, and a published compatibility contract so time does not quietly erode the work.

Product detail and release information are at pal.aic.io. If you are planning Foundry or AIP work in .NET and want to talk through the approach, get in touch.