[jd-lara]

This PR is pretty large becuase it adds the capability to add TypeScript autogenerated with validation using zod.

[jd-lara]

Reviewer's guide

This PR looks enormous — 151,790 insertions — but ~147,500 of those are generated model code and ~4,700 are lockfiles. The actual hand-written surface is ~4,800 lines added / ~600 removed.

Nothing under python/src/power_openapi_models/*/models.py, typescript/src/*/models.ts, typescript/src/*/index.ts, or typescript/orval.config.ts is hand-written. All of it is regenerated from SiennaSchemas, and CI fails if it drifts. Skip those files.

---

What this does

Ships power-openapi-models 0.1.0 to PyPI and @sienna-platform/power-openapi-models 0.1.0 to npm from one repo, one schema pin, one tag — with a prepared slot for Rust.

Decision	Choice
Layout	Symmetric monorepo: python/, typescript/, rust/ slot
TS output	orval client: 'zod' — runtime validation at parity with pydantic, not types only
npm shape	One package, six subpath exports, mirroring the Python distribution
Versioning	Lockstep — one version, one v* tag, fanned out to every registry
Parity	Hand-written document.ts and a blocking Python↔TypeScript CI gate

Structure

├── .schema-version          ONE pin, every language
├── fixtures/                shared — both languages round-trip the same bytes
├── codegen/
│   ├── python/postprocess.py
│   └── typescript/{gen-orval-config,postprocess,domains}.ts
├── scripts/
│   ├── check_cross_language.py    the equivalence gate
│   └── check_version_sync.py      lockstep enforcement
├── python/          pyproject.toml, src/, tests/, README
├── typescript/      package.json, src/, tests/, README
└── rust/            README only — upcoming

---

Suggested review order

1. Start here — the gate. scripts/check_cross_language.py

It compares the generated surfaces field by field: names, requiredness, enum values, scalar kinds, defaults. Python↔TypeScript is blocking; Python↔Julia is report-only (see below).

It was passing vacuously before this PR. It matched Base.@kwdef mutable struct while the Julia generator emits Base.@kwdef struct, so it parsed zero structs, compared zero types, and printed "Surfaces agree" with exit 0. It now refuses to report agreement when it compared nothing.

2. What the fixed gate found. Both generators silently drop schema defaults, in opposite places — 156 real disagreements, each confirmed against the schema:

• CostCurve(...) omitting vom_cost raised ValidationError in Python while the identical document loaded fine in TypeScript. datamodel-code-generator honours required but drops the default when a property is both.
• An omitted EmissionsData.mass_unit was 'KG' in Python and undefined in TypeScript. orval drops property-level defaults.
• The packages exported different identifiers for the same schema (AGC vs Agc) — orval PascalCases all-caps titles.
• orval also invented a default: FuelCurve.startup_fuel_offtake got a full curve the schema never declares.

All fixed against the schema, generally rather than case-by-case. Now 0 divergences, and the gate still fails on a perturbed default — verified, given its history.

3. The generation pipelines. codegen/typescript/postprocess.ts, codegen/python/postprocess.py

orval has no ref→module mapping (unlike datamodel-codegen's --external-ref-mapping), so each domain re-emits every shared type — 106 duplicates. The postprocess rewrites each into a re-export only if the bodies are identical, and otherwise aborts with a diff rather than guessing which copy wins.

4. The package surfaces. typescript/package.json, typescript/src/document.ts, python/src/power_openapi_models/document.py

document.ts is hand-written, mirroring Core/SystemDocument.json, because that schema is deliberately excluded from the six generated specs. It's the counterpart of document.py.

5. Release machinery. .github/workflows/, scripts/check_version_sync.py

One v* tag fires both release workflows; both gate on version sync, which fails when manifests disagree, when the tag doesn't match, and — with --require — when a manifest a release claims to publish is absent.

---

Things worth a reviewer's attention

write_document did not round-trip. It materialized name/description/frequency as explicit nulls (adding three keys the input never had), emitted keys in field-declaration order, and omitted the trailing newline. Both fixtures now round-trip byte-identically. Note exclude_unset, not exclude_none — time_series_storage_file is required and legitimately null, so dropping every None strips a required key.

One documented asymmetry. TypeScript re-orders $.ext keys to ascending numeric order: ECMAScript enumerates integer-like own properties that way in every engine. Exactly one object per fixture is affected, content is untouched, and key order isn't significant per RFC 8259. The tests assert this is the only difference, so it can't grow.

Python↔Julia is report-only, deliberately. It reports ~300 divergences from one confirmed pre-existing bug in PowerOpenAPIModels: an omitted defaulted field decodes to ABSENT there where Python materializes the schema default (verified by running both — SEXS without V_ref is ABSENT in Julia, 1.0 in Python). Not fixable by editing generated code here. It prints in full on every run, so the count can't quietly grow. To be filed separately against that repo.

Exemptions could only rot. They were looked up only from detected divergences, so an entry whose divergence stopped occurring went permanently silent while still reading as coverage. A rot detector now fails the run on an exemption matching nothing — it immediately found three stale entries, two describing a Java generator that repo no longer uses.

---

Before this can release

Three steps outside the diff:

1. Branch protection — the required check test no longer exists. Jobs are now schema-sha, python, typescript, version-sync, cross-language.
2. npm first publish must be manual — npm has no pending-publisher flow, so a trusted publisher can only attach to a package that already exists: cd typescript && npm publish --access public once, then wire the trusted publisher. The workflow is written for OIDC and fails until then rather than falling back to a stored token.
3. PyPI pending publisher — configure before tagging, since the project is unclaimed.

Then git tag v0.1.0 && git push --tags releases both.

---

Verification

Gate exit 0 · both generators idempotent, byte-identical output · 52 Python + 27 TypeScript tests · both fixtures round-tripping byte-identically · tsc --noEmit 0 errors · subpath exports verified by installing the packed tarball (ESM + CJS) · npm publish --dry-run 2.2 MB / 112 files with no src/, orval, or codegen leakage.