Skip to content

Release camelCase contract surface for 0.12.0 - #2

Merged
IslamBaraka90 merged 2 commits into
mainfrom
agent/catalog-contract-followup
Aug 6, 2026
Merged

Release camelCase contract surface for 0.12.0#2
IslamBaraka90 merged 2 commits into
mainfrom
agent/catalog-contract-followup

Conversation

@IslamBaraka90

@IslamBaraka90 IslamBaraka90 commented Aug 5, 2026

Copy link
Copy Markdown
Owner

Everything for the 0.12.0 release, in two commits.

No algorithms were added or removed: 324 topics before, 324 after. What changes
is the surface in front of them.

Breaking

  • 23 entry points renamed snake_case → camelCase (bollinger_bands
    bollingerBands, true_rangetrueRange, double_topdoubleTop, …).
  • 110 sibling re-exports removed across 28 subpaths. .../momentum/rsi no
    longer re-exports williamsR, connorsRsi, stochasticRsi or
    ultimateOscillator — a subpath is one function, and the symbol did not
    disappear, it stopped being in more than one place.
  • Payload schema 1.0.0 → 2.0.0. Per-topic languages is now
    catalogLanguages.

Both code-level tables are in CHANGELOG.md, generated by diffing the published
0.11.0 payload rather than hand-typed.

Added

  • CommonJS can resolve the package. Every entry in the exports map now
    declares a require condition alongside import, both pointing at the same
    ES module. CommonJS consumers were failing at resolution, not loading —
    import is not a condition require() matches — so there is no second build,
    the tarball is the size it was, and a dual-package hazard is impossible.
    Refs Support for CommonJS / dual module exports #1.
  • The payload describes the surface that serves it. package now states the
    runtime facts an agent previously had to infer (type, engines, root export
    is metadata-only, algorithms are subpath-only) and names the machine surface:
    /llms.txt, /version.json, /reference/payload.json, and the per-domain and
    per-topic route patterns. Every route was requested against the live site
    before being written down.
  • archetypes, the five input shapes as data — derived counts, the canonical
    TypeScript input type, a minimal payload that executes, and the validator to
    run at the boundary. The machine half of /guides/archetypes/.
  • domains[].slug, so a domain's URL is no longer rediscovered by finding
    one of its topics and splitting its path.
  • CHANGELOG.md, which also ships inside the tarball.

Improved

0.11.0 0.12.0
Topics with a validated api contract 280 / 324 324 / 324
Topics with a fixture-verified worked example 88 158
Topics with any worked example 279 324

Guardrails

  • gen-docs.mjs takes --strict-contracts and refuses to emit when a topic has
    no api: block; CI additionally asserts coverage over the committed payload,
    so it runs on every pull request whether or not the catalog checkout is
    available. Coverage that nothing enforced is how a complete 271/271 quietly
    became 280/324.
  • The generator refuses to emit a payload whose own structure is inconsistent —
    a domain spanning two path roots, or an archetype with no description.
  • CI and the release workflow both smoke-test the packed tarball from CommonJS
    as well as ESM, against a clean consumer install.

Validation

  • npm run verify — 493/493 tests.
  • docs.json byte-identical on re-run; gen-docs.mjs --check --strict-contracts
    passes.
  • Packed tarball installed into a clean consumer and imported from both ESM and
    CommonJS.
  • All four archetype examples executed against the built package. Two of them
    caught real errors in the published guide's snippets, which are corrected in
    the payload.

Known issue, unrelated to this branch

npm run sync currently fails: the catalog has grown a family of ten topics
that share one calculate() dispatcher, and sync refuses to emit until each has
its own entry point. Nothing in this branch depends on resolving that — the
registry is unchanged at 324 topics, and docs.json regenerates from it — but
the exports map could not be produced by re-running sync. It was rewritten in
place instead and then checked against what the updated generator produces for
the same 324 paths, so the next successful sync is a no-op on package.json.

The exports map now declares a `require` condition alongside `import`, both
pointing at the same ES module. CommonJS consumers were failing at resolution
rather than loading — `import` is not a condition `require()` matches — so no
second build is needed, the tarball is unchanged in size, and there is no
dual-package hazard. Refs #1.

docs.json moves to schema 2.0.0, so a consumer holding only the payload can
find the surface that serves it:

  - `package` states the runtime facts an agent previously had to infer (type,
    engines, root export is metadata-only, algorithms are subpath-only) and
    names the machine surface: /llms.txt, /version.json,
    /reference/payload.json, and the per-domain and per-topic route patterns.
    Every route was requested against the live site before being written down.
  - `archetypes` is new — the five input shapes as data, with derived counts,
    the canonical input type, a minimal payload that executes, and the
    validator to run at the boundary.
  - `domains[].slug` is new, so a domain's URL no longer has to be rediscovered
    by finding one of its topics and splitting the path.
  - per-topic `languages` becomes `catalogLanguages`, read from the catalog's
    implementations/ directories instead of hard-coded. The package ships
    TypeScript alone and now says so once, as `package.languages`.

The generator also refuses to emit a payload whose own structure is
inconsistent, and takes --strict-contracts to refuse one where a topic has no
api: block at all.

CHANGELOG.md records the 0.12.0 migration: 23 snake_case entry points renamed
to camelCase, and 110 sibling re-exports removed across 28 subpaths. Both
tables are generated by diffing the published 0.11.0 payload, and the file now
ships inside the tarball.

CI gains the contract-coverage gate and a CommonJS smoke test of the packed
tarball alongside the existing ESM one.
@IslamBaraka90
IslamBaraka90 merged commit 46dd929 into main Aug 6, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant