feat(api.ht): shapes tool — link-shape comparison for dot-do/data#36

[nathanclevenger]

Integrates the dot-do/data#36 link-shape examples INTO the live api.ht v0.1.0 worker as one new registry tool — per the founder ruling (2026-08-24): integrate and coordinate, no parallel implementations.

What it adds

One HypertextTool, shapes, in the worker's own conventions (same respond envelope, same LinkContext grammar, same registry expansion path — no second envelope):

• The SAME entity in three candidate link shapes, switched by ?shape=:
  • a — typed camelCase edges: the envelope links block keyed by verb-register edge names (postedBy, locatedIn, memberOf, sameAs, potentialAction)
  • b — label-keyed maps: links keyed by arbitrary human labels, as the original recovered workers did
  • c — typed + variations: shape (a) plus a data.variations block of REAL representation alternates (classes: Wikidata JSON / TTL / HTML; jobs: Greenhouse HTML + board-API JSON) — relation edges and representation alternates never share a namespace
• Every JSON response carries a data.shapes hop map to the same page in the other two shapes, so the founder can compare in place.
• A miss is a page: 404 + suggestions rendered as the current shape's link map.
• The tool root is a clickable HTML index explaining the three shapes (new optional HypertextTool.landingHtml, reusing the property's shared page shell).
• Data embedded at build time, zero request-time fetches: the 53 canonical Job records (dot-do/data#34 adapter PoC, 3 Greenhouse boards) + top-20 head Wikidata classes (committed wiki-sources catalog, snapshot 2026-08-23, CC0-1.0), plus companies/locations Views over jobs.
• Framework deltas kept minimal: optional landingHtml on HypertextTool; encodeValue now keeps / readable so multi-segment values are first-class; page/esc exported from landing.ts.

Routes once deployed

• https://shapes.api.ht/ — clickable index explaining the three shapes
• https://shapes.api.ht/jobs/4266196009?shape=a · ?shape=b · ?shape=c — same job, three shapes
• https://shapes.api.ht/classes/Q5?shape=a · ?shape=b · ?shape=c — same class; shape c carries real Wikidata JSON/TTL/HTML alternates
• https://shapes.api.ht/jobs/staff-engineer?shape=a and https://shapes.api.ht/classes/Q42?shape=c — the deliberate misses, suggestions as link maps
• https://shapes.api.ht/jobs?shape=b · https://shapes.api.ht/classes?shape=a — dataset indexes; https://shapes.api.ht/companies/10alabs?shape=c — a View over jobs
• Local dev (path mode): http://localhost:8787/shapes/jobs/4266196009?shape=a

Verification

• tests/api-ht.test.ts: 34/34 green (12 new shapes tests, fully offline)
• Framework typecheck (tsc -p tsconfig.json) and example typecheck: clean
• build.ts bundle: OK (221KB _worker.js)
• wrangler dev --local smoke-tested: all three shapes, hop maps, miss pages, HTML landing, apex tool index — all verified
• Pre-existing e2e/spike suite failures (live api.example.com.ai URLs / workerd) are unrelated to this change
• NOT deployed — deploy authority stays with the founder/owning session

Supersedes

Closes the loop on dot-do/data#36 and feeds the dot-do/data#13 per-brand link-contract ruling. The standalone api-ht-live-demo.dotdo.workers.dev worker and the data-repo branch poc/api-ht-live-demo are SUPERSEDED by this PR and should be torn down after merge + deploy.

🤖 Generated with Claude Code