Distribute ontology SDK packages

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

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:

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 4 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.

{
  "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.

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:

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:

{
  "version": 1,
  "runtimes": [
    {
      "language": "java",
      "package": {
        "name": "consumer-sdk",
        "groupId": "com.bijection",
        "module": "com.bijection.consumer",
        "version": "0.2.0"
      },
      "files": ["consumer-sdk-0.2.0.jar", "consumer-sdk-0.2.0-sources.jar", "consumer-sdk-0.2.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:

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 for that channel workflow. Standalone CLI/MCP targets use SDK binary builds. The sealed registry workflow here handles TypeScript, Python wheels, Go, Java and OpenAPI.

Get Started

Use-case atlas

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Distribute ontology SDK packages

Build and release

Destination profiles

Identities, recovery and installation evidence

npm channels and rollback

Publish shared runtimes

​Build and release

​Destination profiles

​Identities, recovery and installation evidence

​npm channels and rollback

​Publish shared runtimes

Build and release

Destination profiles

Identities, recovery and installation evidence

npm channels and rollback

Publish shared runtimes