docs(api): inventory and document non-conflicting TypeScript API

[seonghobae]

Purpose

Advance #82 with a deterministic repository-wide TypeScript export inventory plus a non-conflicting documentation slice. This branch is intentionally Draft because src/index.ts and src/worker.ts remain active source surfaces in #83/#71; it does not race those branches or pretend the repository-wide documentation requirement is complete.

Exact source identity

• Base: main at live tip 9adb784902cae19a150146a8fadd6a0491f67814, revalidated immediately before this metadata update.
• Head branch: docs/rate-limit-public-api.
• Exact head: d6194f5407a33e0db0d556669c6df9d30a8c63f1.
• Draft remains intentional until the remaining active-source documentation gaps can be integrated without racing their writers and exact-head gates are clean.

Implemented on this branch

Runtime behavior is unchanged. The branch adds or improves beginner-readable public JSDoc on non-conflicting credential-boundary modules:

• src/rate-limit.ts: environment/decision/error contracts, trusted client identity, hashed bucket identity, distributed check, Durable Object constructor/methods, cleanup semantics;
• src/entrypoint.ts: runtime environment, bounded exchange request, exact GitHub origin trust, bounded OIDC bearer envelope, streamed JSON byte boundary, default Worker/fetch contract;
• src/runtime-entrypoint.ts: deployment environment and /ready-owning Worker wrapper;
• src/outbound-fetch-policy.ts: fetch host/callable contracts, destination/request allowlists, fail-closed redirect/response-size/timeout behavior, installation/tamper detection, test-only reset;
• src/oidc-replay.ts: replay environment/decision/errors, hashed jti object identity, atomic claim, Durable Object constructor/fetch/alarm semantics.

test/rate-limit-public-api-docs.test.ts now recursively discovers every owned src/**/*.ts file using the filesystem and parses source text with the TypeScript compiler API without importing or executing production modules. It inventories direct exported interfaces/types/classes/functions/enums/modules/variables and default exports, requires meaningful adjacent JSDoc, requires @param/@returns on discovered callable exports, and permits named re-exports only when a single documented original exists (or the re-export itself is documented). Targeted assertions retain security/trust semantics for the credential-boundary modules instead of accepting label-only comments.

Test-first lineage

The slice was developed incrementally: each newly covered module was first added to the static documentation contract while its public declarations were still undocumented, followed by a comment-only source remediation. d6194f5407a33e0db0d556669c6df9d30a8c63f1 then replaces the narrow marker-only inventory with the recursive TypeScript AST inventory required by #82. The repository-wide inventory is intentionally capable of exposing remaining active-file gaps; current CI evidence must determine the exact remaining set rather than this body asserting GREEN prematurely.

Deliberately deferred, not waived

• src/index.ts and src/worker.ts documentation: active in fix(security): claim verified OIDC replay before token mint #83/fix(security): bind workflow source and document MSA boundaries #71, so this branch will not race them.
• src/runtime-readiness.ts: already carries substantial public JSDoc on protected main and is also part of fix(security): bind workflow source and document MSA boundaries #71's active architecture/runtime work; it is inventoried read-only by the recursive gate.
• CI/release documentation integration (docs/TEST_STRATEGY.md, CLAUDE.md, CHANGELOG) and any canonical architecture wording that overlaps fix(security): bind workflow source and document MSA boundaries #71/fix(review): authorize private target PR lookup with Noema App #85 are deferred until those active branches integrate.
• quality(api): enforce 100% beginner-readable TypeScript public API documentation #82 is therefore still open. No acceptance criterion, governance gate, security gate, coverage threshold, approval requirement, release requirement, or licensing/IP requirement is weakened.

Acceptance

Before leaving Draft, refetch unchanged exact head and independently resolved live base; resolve every inventory gap after its active writer lease clears; require exact-head typecheck/tests/100% owned production coverage/security/reviewer gates, zero valid unresolved findings, and actual Noema governance including qualifying independent approval where required. Queued/status/model evidence is not merge authority.

Related: #82, #71, #76, #83, #85

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 58c347bf-0246-46f3-858b-3905374e92cd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}