> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Distribute ontology SDK packages

> Build once, publish immutable packages, and verify independent consumers

The publisher selects a public contract with `bijection sdk generate`, commits the
configuration and complete lock, and releases ordinary language packages. Consumers
install those packages without producer source. Shared Bijection runtime releases
are separate from customer ontology packages.

## Build and release

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection sdk release build \
  --config bijection.sdk.json \
  --runtime-catalog vendor/runtime-catalog.json \
  --runtime-bundle vendor/application-runtimes \
  --out dist/business-sdk

bijection sdk release inspect --bundle dist/business-sdk --format json

bijection sdk release publish \
  --bundle dist/business-sdk \
  --publish-config bijection.sdk.publish.json \
  --profile production
```

The optional runtime bundle supplies prepared Java compilation dependencies in an
owned Maven cache. It must match the catalog exactly. Without it, Maven must already
be configured to resolve the pinned runtime. No runtime is compiled from source by
this build, except that Go distributes its ordinary source module.

`build` renders from the complete lock, packs npm and wheel distributions, compiles
Java using prepared language tools, and seals Go module and OpenAPI artifacts.
Generation is offline; package builds can require dependency downloads unless the
language caches are prepared. The CLI never starts a backend or provisions compute.

`publish` checks runtime availability and all target coordinates, installs candidates,
publishes the sealed files, downloads them using consumer credentials, and installs
them in fresh applications. It checks shipped examples and client construction
without calling a deployment. Existing identical versions are retained; conflicting
versions are refused.

For a single CI invocation:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection sdk release run \
  --config bijection.sdk.json \
  --runtime-catalog vendor/runtime-catalog.json \
  --runtime-bundle vendor/application-runtimes \
  --publish-config bijection.sdk.publish.json \
  --profile production \
  --out dist/business-sdk
```

Repeating `run` reuses the sealed bundle when its inputs match. Changed inputs
require another output directory. `publish` never rebuilds. `publish --dry-run`
validates the bundle and profile and emits a plan without writes or network access;
it does not establish credential permissions or destination availability.

Prepared tools are selected with `--node`, `--npm`, `--pnpm`, `--tsc`, `--python`,
`--go`, `--git`, `--java`, `--maven`, and `--aws`. Python needs `build`, `hatchling`,
Twine, mypy and Pyright installed. The selected tools are recorded in receipts.
No tool bootstrap is performed. Only tools for the selected languages are needed.

## Destination profiles

Keep distribution routing separate from the version 5 SDK configuration. The
following URLs, repository names and credential references are examples; replace
them with existing organization resources. A profile must select exactly the
languages in its bundle.

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "version": 1,
  "profiles": {
    "production": {
      "targets": {
        "typescript": {
          "kind": "npm",
          "registry": "https://packages.acme.example/npm/",
          "defaultRegistry": "https://registry.npmjs.org/",
          "access": "restricted",
          "publishCredential": "env:NPM_PUBLISH_TOKEN",
          "readCredential": "env:NPM_READ_TOKEN"
        },
        "python": {
          "kind": "python",
          "uploadUrl": "https://packages.acme.example/python/",
          "indexUrl": "https://packages.acme.example/simple/",
          "publishCredential": "env:PYTHON_PUBLISH_TOKEN",
          "readCredential": "env:PYTHON_READ_TOKEN"
        },
        "java": {
          "kind": "maven",
          "registry": "https://packages.acme.example/maven/",
          "username": "sdk-release",
          "publishCredential": "env:MAVEN_PUBLISH_TOKEN",
          "readCredential": "env:MAVEN_READ_TOKEN"
        },
        "go": {
          "kind": "git",
          "repository": "git@github.com:acme/business-sdk.git",
          "proxy": "https://packages.acme.example/go/",
          "privateModules": "example.com/acme/*"
        },
        "openapi": {
          "kind": "s3",
          "bucket": "acme-sdk-artifacts",
          "prefix": "ontology",
          "awsProfile": "sdk-publisher",
          "awsReadProfile": "sdk-consumer"
        }
      },
      "runtimeSources": {
        "go": {
          "kind": "git",
          "proxy": "https://packages.acme.example/go/",
          "privateModules": "example.com/acme/*"
        }
      }
    }
  }
}
```

Runtime reads default to the corresponding target destination. Use `runtimeSources`
to route a runtime elsewhere, as for the Go example above. Python and Maven indexes
must resolve their normal transitive dependencies; Go's consumer proxy must also
resolve its runtime. npm's `defaultRegistry` controls ordinary dependencies while
the generated customer and runtime scopes use their explicit repositories.

Tokens are environment references, never literal values in the profile. npm uses
bearer authentication; Python and Maven use basic authentication with the supplied
token as password and `username` (default `__token__`). Go uses native Git/proxy
credentials. S3 uses native AWS credentials or named profiles. Supply read credentials
independently from publication credentials. HTTPS is required except for loopback
protocol checks. Additional artifact/CDN hosts require explicit `downloadHosts`.

Supported Maven destinations accept immutable release files at standard Maven2 HTTP
paths. The adapter uploads the existing JAR and original POM with conditional PUTs,
so it can resume a partially uploaded release. Configure the repository to refuse
redeployments. Provider-specific staging services, including services requiring a
separate release API, need their own adapter. Snapshot versions are refused.

Go publication creates a commit and version tag in an existing SDK repository,
without pushing a branch or forcing tags. `subdir` selects an owned module directory;
tags include that directory prefix. Existing generated files are checked against
their ownership manifest, and unowned files are preserved. Versions 2 and later
retain Go's `/vN` module path requirement. S3 uses conditional creation under the
configured prefix and requires list/get permissions for consumer readback.

## Identities, recovery and installation evidence

The release directory contains an immutable `bundle/manifest.json`, sealed sources
and archives, candidate evidence, destination-bound publication journals, and an
installation kit. Its identity binds the generator, producing CLI binary, reviewed
input hashes, contract identities, runtime requirements and final archive hashes.
Go additionally retains native module content sums; equivalent ZIP compression
does not change a Go module's content identity.

A checksum is an integrity identity, not a publisher signature. Exact direct runtime
pins do not lock every transitive dependency.

Publication is coordinated across targets, but it is not a cross-registry
transaction. An interrupted command retains completed targets and reconciles
uncertain uploads through readback. Re-run `publish` with the same bundle and
profile to finish. Authentication failures are not treated as missing packages.
Private execution directories are removed; sealed bundles and receipts remain.
An operating-system lock prevents simultaneous commands from owning one bundle.

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection sdk release verify \
  --bundle dist/business-sdk \
  --publish-config bijection.sdk.publish.json \
  --profile production
```

`verify` publishes nothing. It downloads and installs exact versions with consumer
credentials. The successful receipt has evidence `published_distribution` and lists
the executed cases, archive observations, tool versions and cleanup result. It
does not establish deployed ontology behavior. Candidate installation and controlled
registry tests are separate evidence levels.

The generated `install/<profile-digest>/` directory contains the exact installation
commands, credential placeholders, registry settings, runtime configuration and
upgrade instructions. Business tokens and deployment URLs are supplied by each
application at runtime. Package installation grants no business authorization.

## npm channels and rollback

Publication uses a release-specific npm tag. Updating a consumer channel is explicit
and repeats destination verification first:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection sdk release promote --bundle dist/business-sdk \
  --publish-config bijection.sdk.publish.json --profile production --channel stable
```

Promote an older bundle to select its older version. Immutable packages are not
deleted or overwritten. Other ecosystems use exact versions through their normal
dependency manifests; no universal mutable channel is invented for them.

## Publish shared runtimes

Bijection release maintainers prepare the npm archive, Python wheel, Go module
source and Java JAR/POM using their existing owners. Describe the prepared inputs:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "version": 1,
  "runtimes": [
    {
      "language": "java",
      "package": {
        "name": "consumer-sdk",
        "groupId": "com.bijection",
        "module": "com.bijection.consumer",
        "version": "0.3.0"
      },
      "files": ["consumer-sdk-0.3.0.jar", "consumer-sdk-0.3.0-sources.jar", "consumer-sdk-0.3.0-javadoc.jar", "pom.xml"]
    }
  ]
}
```

Input paths are relative to this file. Runtime bundles may contain any subset of
the four supported runtimes. A customer build's catalog must contain every exact
runtime pin in its lock. The internal release owner delegates to the same engine:

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
stack release packages consumer-runtimes \
  --cli /path/to/bijection --inputs runtime-inputs.json --output dist/runtimes \
  --publish --publish-config runtime-publish.json --profile production
```

Successful runtime publication and independent installation emit
`dist/runtimes/runtime-catalog.json`. A candidate catalog used in source CI carries
candidate identities only; it does not establish real registry availability.

The release engine does not host registries, create repositories or buckets, change
registry access policies, or automatically upgrade consuming applications. Python generation also emits native Conda recipes; see the [Python consumer guide](/client/python/consumer-sdk) for that channel workflow. Standalone CLI/MCP targets use [SDK binary builds](/client/agent-packages). The sealed registry workflow here handles TypeScript, Python wheels, Go, Java and OpenAPI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.