feat: add and publish TypeScript adapter contract

.agents/skills/contribute-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: contribute-api
-description: Contribute a new NeMo Fabric public API surface safely, with Rust, CLI, Python, schema, adapter, and documentation parity in mind
+description: Contribute a new NVIDIA NeMo Fabric public API surface safely, with Rust, CLI, Python, TypeScript, schema, adapter, and documentation parity in mind
 author: NVIDIA Corporation and Affiliates
 license: Apache-2.0
 ---
@@ -20,8 +20,8 @@ runtime or bindings.
 ## Default Guidance
 
 - Start from the shared Rust core behavior first
-- Decide whether the CLI, PyO3 binding, Python SDK, type stubs, schemas, or
-  adapter contract must expose the new surface
+- Decide whether the CLI, PyO3 binding, Python SDK, type stubs, schemas, or the
+  Python and TypeScript adapter-contract bindings must expose the new surface
 - Keep every affected public surface in parity
 - Update docs and examples in the same branch
 
@@ -37,4 +37,5 @@ runtime or bindings.
 - `validate-change`
 - `review-doc-style`
 - `docs/python-sdk-contract.md`
+- `schemas/SCHEMA.md`
 - `justfile`

.agents/skills/maintain-ci/SKILL.md

@@ -29,6 +29,10 @@ reliability, or reproducibility.
   `actions/cache`.
 - Use lockfiles or dependency manifests to drive cache invalidation.
 - Keep deploy and publish permissions isolated to the jobs that need them.
+- Publish the TypeScript contract from the dedicated
+  `publish_typescript.yml` workflow through the protected `npmjs` environment.
+  Grant `id-token: write` for npm trusted publishing, and do not provide an npm
+  write token that could mask an OIDC configuration failure.
 - Read both caller and callee when a workflow uses `workflow_call`.
 - Keep documentation publish and preview credentials isolated to the Fern docs
   workflow.
@@ -42,8 +46,11 @@ reliability, or reproducibility.
 - `contents: read` is the default minimum for checkout-based build, test, docs,
   and packaging jobs.
 - `pull-requests: read` is required for PR metadata lookup jobs.
-- `pages: write` and `id-token: write` should be limited to Pages deployment
-  jobs and any caller that invokes them through a reusable workflow.
+- `pages: write` should be limited to Pages deployment jobs and any caller that
+  invokes them through a reusable workflow.
+- `id-token: write` should be limited to jobs that exchange a GitHub OIDC token
+  with a protected deployment target, including Pages deployment and the
+  protected npm publication job.
 - For reusable workflows, the caller must grant every permission the called
   jobs require. The callee cannot elevate beyond what the caller provides.
 
@@ -93,6 +100,8 @@ source instead of assuming local success proves remote success.
 - `.github/workflows/fern-docs.yml`
 - `.github/workflows/nightly-alpha-tag.yml`
 - `.github/workflows/publish_rust.yml`
+- `.github/workflows/publish_typescript.yml`
+- `scripts/ci/publish_typescript_package.py`
 - `.gitlab-ci.yml`
 - `RELEASING.md`
 - `Cargo.lock`

.agents/skills/maintain-packaging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maintain-packaging
-description: Maintain NeMo Fabric Rust and Python dependencies, package metadata, module paths, native artifacts, lockfiles, license evidence, and release-facing build surfaces
+description: Maintain NVIDIA NeMo Fabric Rust, Python, and TypeScript dependencies, package metadata, module paths, native artifacts, lockfiles, license evidence, and release-facing build surfaces
 author: NVIDIA Corporation and Affiliates
 license: Apache-2.0
 ---
@@ -24,9 +24,13 @@ consumed outside the source tree.
 - Python package metadata in `python/pyproject.toml`
 - Native extension naming and placement under `python/src/nemo_fabric`
 - Dependency resolution in `Cargo.lock` and `uv.lock`
+- TypeScript adapter-contract metadata and dependency resolution in
+  `typescript/adapter-contract/package.json` and `package-lock.json`
 - Documentation tooling metadata in `docs/package.json` and
   `docs/package-lock.json`
 - CI workflows, install commands, and example commands
+- npm trusted publishing through `.github/workflows/publish_typescript.yml` and
+  the protected `npmjs` environment
 - `justfile` build, test, clean, and documentation recipes
 - Release tags, registry publication, and release-facing documentation in
   `RELEASING.md`
@@ -59,6 +63,10 @@ commitment.
   `uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main`
   after updating manifests and lockfiles, then review added packages and license
   changes.
+- For `typescript/adapter-contract/package-lock.json`, inspect the resolved
+  package entries and their `license` fields. The adapter-contract package must
+  keep an empty production dependency graph; build-only dependencies still
+  require permissive, recorded license evidence.
 - Regenerate the attribution files with the named pre-commit hooks instead of
   editing generated output:
 
@@ -78,6 +86,8 @@ compatibility decisions using the distribution and linkage context.
 - [ ] CI references the same package names as local workflows
 - [ ] Public packaging changes are reflected in release-facing docs
 - [ ] Workspace, Python, and lockfile versions remain aligned where required
+- [ ] The TypeScript adapter-contract package version follows the workspace
+      release version without changing its independent wire contract version
 - [ ] The editable maturin build still produces `nemo_fabric._native`
 - [ ] New dependencies are necessary, maintained, and narrower than the viable
       alternatives
@@ -96,6 +106,11 @@ compatibility decisions using the distribution and linkage context.
 - `uv.lock`
 - `docs/package.json`
 - `docs/package-lock.json`
+- `typescript/adapter-contract/package.json`
+- `typescript/adapter-contract/package-lock.json`
+- `.github/workflows/ci_typescript.yml`
+- `.github/workflows/publish_typescript.yml`
+- `scripts/ci/publish_typescript_package.py`
 - `.github/workflows/ci_python.yml`
 - `.github/workflows/ci_rust.yml`
 - `.pre-commit-config.yaml`

.agents/skills/update-project-version/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update-project-version
-description: Update the NeMo Fabric release version across Cargo, setuptools package metadata, internal Python dependency pins, integration metadata, and lockfiles. Use when bumping, synchronizing, or auditing NeMo Fabric package versions for a release.
+description: Update the NVIDIA NeMo Fabric release version across Cargo, Python, and TypeScript package metadata, internal Python dependency pins, integration metadata, and lockfiles. Use when bumping, synchronizing, or auditing NeMo Fabric package versions for a release.
 author: NVIDIA Corporation and Affiliates
 license: Apache-2.0
 ---
@@ -20,7 +20,8 @@ pre-release or build-metadata variants used during packaging.
 ## Source Of Truth
 
 - `Cargo.toml` `[workspace.package].version` is the source of truth for the Rust
-  workspace and Python build versioning.
+  workspace and the release version stamped into Python and TypeScript package
+  metadata.
 - Keep `Cargo.toml` `[workspace.dependencies]` self-references aligned when the
   workspace version changes.
 - `python/pyproject.toml` is the exception among the Python projects: do not add
@@ -36,6 +37,8 @@ pre-release or build-metadata variants used during packaging.
   - All `nemo-fabric-* == <version>` requirements in the root
     `pyproject.toml` optional dependencies.
   - Each adapter's `nemo-fabric-adapters-common == <version>` dependency.
+- Keep `typescript/adapter-contract/package.json` and the root package entries in
+  its `package-lock.json` aligned with the Cargo SemVer release version.
 
 For a normal release, use the same `X.Y.Z` string everywhere. For a prerelease
 or build-metadata version, use valid Cargo SemVer in `Cargo.toml` and the
@@ -45,15 +48,17 @@ versions rather than blindly copying incompatible syntax.
 
 ## Workflow
 
-1. Read the current version from `Cargo.toml` and decide the exact Cargo and
-   Python target version strings.
-2. Run `just set-version <cargo-version>`. The recipe converts supported Cargo
-   SemVer prereleases to PEP 440 and updates:
+1. Read the current version from `Cargo.toml` and decide the exact Cargo,
+   Python, and TypeScript target version strings.
+2. Run `just set-version <cargo-version>`. The recipe preserves the normalized
+   SemVer for Cargo and TypeScript, converts it to PEP 440 for Python, and
+   updates:
    - `Cargo.toml` `[workspace.package].version`
    - `Cargo.toml` `workspace.dependencies.nemo-fabric-core.version`
    - The root setuptools `project.version` and every
      `adapters/**/pyproject.toml` `project.version`
    - Every internal `nemo-fabric-*` exact-version requirement
+   - The TypeScript adapter-contract `package.json` and `package-lock.json`
    - `Cargo.lock` through Cargo metadata resolution
    - The root, runtime, and adapter `uv.lock` files through `just lock-python`
 3. Confirm that `python/pyproject.toml` remains dynamic and unchanged.
@@ -62,14 +67,17 @@ versions rather than blindly copying incompatible syntax.
 
 If editing the helper code, keep these contracts aligned:
 
-- `set_project_version` must call the Cargo and Python project version helpers.
+- `set_project_version` must call the Cargo, Python, and TypeScript project
+  version helpers.
 - `set_cargo_workspace_version` must update the workspace version and the
   `nemo-fabric-core` workspace dependency, then verify every `nemo-fabric-*` workspace
   package through Cargo metadata.
 - `set_python_project_versions` must update the root setuptools version, every
   adapter `pyproject.toml` discovered recursively under `adapters/`, and all
   internal exact-version pins while rejecting a static version in
   `python/pyproject.toml`.
+- `set_typescript_project_version` must update the package manifest and both
+  root version entries in the npm lockfile without changing dependency versions.
 - The `set-version` recipe must run `just lock-python` after source metadata is
   updated.
 
@@ -81,11 +89,14 @@ If editing the helper code, keep these contracts aligned:
   `rg -n '^version =|nemo-fabric-[a-z-]+ == ' pyproject.toml adapters --glob 'pyproject.toml'`
 - Confirm the runtime remains dynamic:
   `rg -n 'dynamic = \["version"\]' python/pyproject.toml`
+- Inspect the TypeScript package and lockfile root versions:
+  `rg -n '"version":' typescript/adapter-contract/package{,-lock}.json`
 - Run `cargo check --workspace --locked`.
 - Run `just build-python` to verify all Python package metadata resolves.
 - Run `just test-python` when the integration version or Python packaging
   behavior changes materially.
 - Run `just wheels` for release-facing validation of every Python wheel.
+- Run `just pack-typescript` to verify the stamped TypeScript package metadata.
 - Run `git diff --check`.
 
 ## Avoid
@@ -94,6 +105,7 @@ If editing the helper code, keep these contracts aligned:
 - Adding a literal version to `python/pyproject.toml`; Maturin owns that version.
 - Updating Python package versions without their exact internal dependency pins.
 - Forgetting `Cargo.lock`, the root `uv.lock`, or per-project `uv.lock` files.
+- Updating the TypeScript package manifest without its npm lockfile root entry.
 - Blind repository-wide replacement of version-like strings.
 
 ## References
@@ -106,4 +118,6 @@ If editing the helper code, keep these contracts aligned:
 - `python/uv.lock`
 - `adapters/**/pyproject.toml`
 - `adapters/**/uv.lock`
+- `typescript/adapter-contract/package.json`
+- `typescript/adapter-contract/package-lock.json`
 - `justfile`

.agents/skills/validate-change/SKILL.md

@@ -23,17 +23,22 @@ surfaces touched by a change.
   test pass.
 - If Rust code changed, run `cargo fmt --all -- --check` and `just test-rust`.
 - If Python code or a Python-facing adapter changed, run `just test-python`.
+- If the TypeScript adapter contract or one of its source schemas changed, run
+  `just test-typescript`.
 - If `crates/fabric-core` changed in a way exposed through Python, run both the
   Rust and Python suites.
 - If the PyO3 bridge or package metadata changed, run `just build-python` and
   `cargo check -p fabric-python --locked`.
 - If public configuration types changed, confirm the schema snapshot tests in
   `just test-rust` pass and review generated schema diffs.
 - If an adapter or integration changed, run its focused tests.
-- If a manifest or lockfile changed, run
+- If a Cargo or Python manifest or lockfile changed, run
   `uv run --no-project python scripts/licensing/license_diff.py --base-ref origin/main`,
   review the transitive license changes, then run the `attributions-rust` and
   `attributions-python` pre-commit hooks.
+- If the TypeScript manifest or npm lockfile changed, inspect the complete npm
+  dependency tree and license fields, confirm the package still has zero
+  production dependencies, and run its package and audit checks.
 - If documentation or examples changed, run `just docs` when practical and
   verify documented commands against the current repository.
 - If code changes alter APIs, commands, paths, packaging behavior, telemetry
@@ -55,8 +60,9 @@ surfaces touched by a change.
 - **Harbor integration changed**
   Run `tests/test_harbor_runner.py`, then `just test-python`.
 - **Schema or public contract changed**
-  Run both language suites and review changes under `schemas/` and generated API
-  references.
+  Run the Rust, Python, and TypeScript suites and review changes under
+  `schemas/`, the checked-in Python adapter-contract representations, generated
+  TypeScript sources, and generated API references.
 - **Documentation-only change**
   Use `contribute-docs` and `review-doc-style`. Run `just docs` for docs-site or
   generated-reference changes.
@@ -69,6 +75,7 @@ surfaces touched by a change.
 ```bash
 just test-rust
 just test-python
+just test-typescript
 ```
 
 ## Common Targeted Commands
@@ -85,6 +92,11 @@ just build-python
 just test-python
 uv run --no-sync pytest -k "<pattern>"
 
+# TypeScript adapter contract
+just build-typescript
+just test-typescript
+just pack-typescript
+
 # Documentation
 just docs
 
@@ -114,5 +126,7 @@ Before review or handoff:
 - Build and test recipes: `justfile`
 - Python CI: `.github/workflows/ci_python.yml`
 - Rust CI: `.github/workflows/ci_rust.yml`
+- TypeScript CI: `.github/workflows/ci_typescript.yml`
 - Documentation CI: `.github/workflows/fern-docs.yml`
 - Public Python contract: `docs/python-sdk-contract.md`
+- Public adapter contract: `schemas/SCHEMA.md`

.github/workflows/ci_typescript.yml

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+name: TypeScript
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-typescript-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    name: Test (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ['20.18.3', '24']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+          cache-dependency-path: typescript/adapter-contract/package-lock.json
+
+      - name: Install just
+        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
+        with:
+          tool: just@1.50.0
+
+      - name: Test TypeScript contract package
+        run: just test-typescript