M141 — dual-registry lockstep publish 📜

How @orchestkit/hook-contract (npm) + orchestkit-hook-contract (PyPI) ship as ONE contract. Approach E from the brainstorm.

One spec, two registries, one version

          spec/hook-events.spec.yml   ← single source of truth (19 events)
                    │ codegen
        ┌───────────┴───────────┐
        ▼                       ▼
  packages/hook-contract   packages/hook-contract-py
  (npm, esm+cjs)           (PyPI, pydantic)
        │                       │
        │   contract-parity.yml gate: npm-side ⇔ pypi-side ⇔ spec (no drift)
        ▼                       ▼
  tag hook-contract-npm/   tag hook-contract-py/
       vX.Y.Z                   vX.Y.Z      ← SAME X.Y.Z (lockstep, enforced)
        │ OIDC                   │ OIDC
        ▼                       ▼
     npm registry            PyPI
        └────────┬──────────────┘
                 ▼  dependabot
     consumers: orchestkit hooks (JS) · yonatan-hq/platform #1809 (Py) · core

Try the lockstep gate (the core of E)

npm package.json

version

HOOK_CONTRACT_VERSION

src/index.ts

pyproject.toml

PyPI

git tag

hook-contract-npm/v
—

Why lockstep (not independent versions)

A contract's value is that consumers reason about ONE number: @orchestkit/hook-contract@1.2.0 ⇔ orchestkit-hook-contract==1.2.0 ⇔ spec v1.2.0. The parity preflight (in BOTH publish workflows) refuses to release unless npm == PyPI == HOOK_CONTRACT_VERSION == tag — so the registries can never drift apart.

Auth: OIDC trusted publishing on both sides — no long-lived NPM_TOKEN (which can shadow gh credentials). One-time trusted-publisher setup per registry.