> For the complete documentation index, see [llms.txt](https://docs.pal.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pal.aic.io/engineering-and-delivery/compatibility-and-generation.md).

# Compatibility and generation

PAL.NET treats API coverage as release evidence. The repository pins an upstream source revision and produces normalized source, manifests, generated contracts, mappings, conformance evidence, and a deterministic gap report.

## Current baseline

The checked-in baseline is derived from Palantir's official `foundry-platform-typescript` repository because a downloadable Foundry OpenAPI document is not published. It records:

* `@osdk/foundry` version `2.82.0`;
* upstream revision `4320149c31bcbcc2d176564d9259e343d9702d2b`;
* minimum API gateway `1.1815.4`;
* 430 imported operations across 27 capabilities;
* 321 public operations in the PAL.NET release scope;
* 2,811 named schema components;
* 0 public compatibility gaps in the current report.

These numbers are release evidence, not permanent product limits. Read the checked-in manifests for the exact baseline used by a release.

## The `palnet` tool

Run from the repository root:

```powershell
dotnet run --project src/PAL.Clients.Tools/PAL.Clients.Tools.csproj -- --help
```

### Import a pinned SDK baseline

```powershell
dotnet run --project src/PAL.Clients.Tools/PAL.Clients.Tools.csproj -- `
  compatibility import-platform-sdk `
  --repository <official-sdk-checkout> `
  --revision 4320149c31bcbcc2d176564d9259e343d9702d2b `
  --retrieved-at 2026-10-06T20:19:43.5889021Z `
  --source-output docs/compatibility/palantir-platform-sdk-v2-source.json `
  --manifest-output docs/compatibility/palantir-platform-sdk-v2-manifest.json
```

The importer records source kind, URI, revision, package version, retrieval time, specification hash, included capabilities, operations, and normalized schemas. Empty or inconclusive sources fail closed.

### Generate models

```powershell
dotnet run --project src/PAL.Clients.Tools/PAL.Clients.Tools.csproj -- `
  bindings generate-models `
  --source docs/compatibility/palantir-platform-sdk-v2-source.json `
  --output-directory src/PAL.Core.Models.Domain/Generated/Platform `
  --namespace PAL.Core.Models.Domain.Generated `
  --generator-version 1.0.0 `
  --manifest-output docs/compatibility/palnet-platform-schemas-manifest.json
```

Model generation removes stale generated model files, writes deterministic UTF-8 source, and records per-file hashes plus an aggregate schema hash.

### Generate platform bindings

```powershell
dotnet run --project src/PAL.Clients.Tools/PAL.Clients.Tools.csproj -- `
  bindings generate-platform `
  --source docs/compatibility/palantir-platform-sdk-v2-source.json `
  --output-directory src/PAL.Core.Services.Domain/Generated/Platform `
  --namespace PAL.Core.Services.Domain.Generated.Platform `
  --models-namespace PAL.Core.Models.Domain.Generated `
  --generator-version 1.0.0 `
  --manifest-output docs/compatibility/palnet-platform-bindings-manifest.json `
  --mappings-output docs/compatibility/palnet-platform-bindings-mappings.json `
  --reviewed-mappings docs/compatibility/palnet-implementation-mappings.json `
  --conformance-output docs/compatibility/palnet-platform-conformance.json
```

Generated clients include operation descriptors, request contracts, typed responses, stream/pagination shapes, error catalogs, and the all-capability registration extension. Reviewed mappings may overlay generated mappings without changing the normalized source.

### Apply mappings and scan gaps

```powershell
dotnet run --project src/PAL.Clients.Tools/PAL.Clients.Tools.csproj -- `
  compatibility apply-mappings `
  --upstream-manifest docs/compatibility/palantir-platform-sdk-v2-manifest.json `
  --mappings docs/compatibility/palnet-platform-bindings-mappings.json `
  --output docs/compatibility/palnet-v2-current-manifest.json `
  --report-output docs/compatibility/palnet-v2-gap-report.json
```

The scanner compares methods, routes, scopes, parameters, request/response media and types, errors, pagination, streaming, stability, and visibility. A release must not claim full parity when public gaps or inconclusive evidence remain.

## Regeneration rules

* Pin the exact source revision and record the retrieval timestamp.
* Regenerate models and bindings from the same normalized source.
* Never hand-edit generated files.
* Review generated diffs, hashes, compilation, serialization, and operation counts.
* Keep hand-authored façades and mappings outside generated directories.
* Treat new upstream operations as coverage work, not an undocumented silent change.