[purpshell]

Summary

Record the feature availability contract merged in polymorfa/polymorfa#561 as a scoped supplement, without adding an SDK method. contracts/feature-evaluation.json holds the four operations and their referenced components: the optional request locale (en, pt-BR), the response fields state (off, opt_in, on), terms and enrollmentSource (customer, staff, null), the always-null exposureToken, the no-effect measurementAllowed, and the exposure route that now always returns 403. All four operations keep their existing coverage exclusions.

The supplement stays pinned to API dev merge commit d36e12ff05f9f3537f3f87d8ad27258abc9b02df (#561). I compared it with the cycle's source pin, API dev e95d02da674da8242453c2a41efd48883fa04734:

• The evaluateFeatures operation object is identical. Its hash in the public docs/api-reference/openapi.json copy is the same at both revisions (b136c410…756e).
• The three account routes (evaluateAccountFeatures, setFeatureEnrollment, recordFeatureExposure) change only description wording. Their fingerprints are unchanged.
• The resolved evaluateFeatures fingerprint changes (06bfd46f…f12a to 44fead3a…a095) only because the shared PublicError code enum gained unrelated codes, such as team_deletion_scheduled and whatsapp_number_not_registered.

Moving the pin would bring that unrelated error enum drift into this PR. The README rule for this supplement assigns shared drift to the next full repin, and scripts/release-gate.mjs does not consume this supplement. So the pin stays at #561, and contracts/README.md records the October 22 reconciliation.

The PR targets main, the repository default branch, which CI and the publication workflow use. The repository has no AGENTS.md, CLAUDE.md, CONTRIBUTING or PR template; this body uses the Polymorfa monorepo template sections.

Impact

Area	Effect and evidence
SDK contract supplement and internal notes	Adds contracts/feature-evaluation.json, scripts/sync-feature-evaluation-contract.mjs, packages/typescript/test/feature-evaluation-contract.test.ts and the supplement section in contracts/README.md. Operation objects are stored unchanged with both source hashes.
API dependency and feature release	Producer is monorepo #561. This records the contract only. Staging and production acceptance and customer availability of feature settings are not verified here.
Overlap with open SDK #359	Both PRs edit contracts/README.md, in different sections. #359 also changes source.json, coverage.json and the Messaging snapshot; this PR does not touch them. Whichever merges second may need a trivial README merge.

No impact table

Area	Reason and evidence
Libraries, runners/Bartender, Temporal, customer and Admin API, Admin controls and MCP	Only SDK contract files, an extraction script and a test change. No runtime, database or migration edits.
SDK runtime, types, handwritten clients and native packages	No package source changes. The four operations stay excluded in contracts/coverage.json; the new test checks the exclusions, the fingerprints and that no package source calls these routes.
Full snapshots, coverage ledger and other supplements	contracts/source.json (171a9683ff45d11a4b5d3917dc428ad2722b0d99), both full snapshots, coverage.json and every other supplement match SDK main.
CLI (polymorfa/cli)	Checked at 58e91a1 (CLI main) and at the open #88 branch: no reference to the evaluate, enrollment or exposure routes, their operation IDs, enrollmentSource, exposureToken, measurementAllowed or termsRevision in source, tests, README or manifest. The generic api command passes bodies and responses through unchanged (src/api/request.ts:49-63, :44-45; src/api/execute.ts:20; src/commands/api.ts:141-165). A local fixture through the real command preserved the locale request and all new response fields in JSON and human output. No CLI PR is needed.
Inspector, Console, Admin Console, onboarding and activation	No UI, identity, enrollment or device flow changes.
Tracking, experiments, billing, Usage, logs, audit logs, customer Analytics	No producer, event, metering or reader changes. The supplement grants no authority and records no exposure.
Public docs, Help Center, marketing	No SDK behavior changes for customers. Public feature documentation belongs to the monorepo delivery levels of this cycle.

Verification

Local run on Node 22.23.2 at e795c07c, mirroring .github/workflows/ci.yml after npm ci:

• format:check, lint, typecheck, build:workspaces, release-gate and Linear coverage node tests, build, check:functions, check:names, npm pack --dry-run, npm audit --omit=dev: all passed.
• check:coverage: 579 operations, 439 covered, 140 excluded, 0 partial, 0 missing, 0 changed, 0 gaps.
• npm test: 1,544 of 1,545 passed. packages/browser/test/package.test.ts timed out at 60 s under machine load; it passed alone in 10.4 s.
• feature-evaluation-contract.test.ts: 5 of 5 passed.
• Regenerating the supplement at d36e12ff0 gives zero diff. At e95d02da67 the only differences are the two source hashes, the PublicError enum and the account-route descriptions.

Source hashes (SHA-256):

File	d36e12ff0 (pinned)	e95d02da67 (compared)
apps/api/docs/openapi.json	03f48a3ac98ff88e504337aaa95d60b1ae81ef3381deaa2d5ac9780896a48608	1c0941904e07d0df1ac9c4b080f237364343e782eaa3a19ff346d5596de65bb2
apps/api/docs/openapi.management.json	baafc9d1836bf1aacdbb550e3e43c6a71e4160d4b4874deb80309b2f43339a10	d5c4f19a14c8cebe943f0de21f2116ae762deff248cc0b2aa0d44e5eb3934b1a
docs/api-reference/openapi.json	f0832eaec81d69ce0066ca451e9011e4cdb10163e95936b454601bdd5561f911	36133621f08cd81c16c4f3ef2ab3f4a09a5508fc80cfc5851044b5efed7d4b2c

Not exercised: live API, staging, production, registry publication and installed consumers. The CLI evidence uses a synthetic response from a local HTTP server.

Session provenance and UI evidence

Delegated Claude subagent (registration purpshell-t3-claude, model Claude Opus 5.5, effort medium) of lead purpshell-t3-claude, T3 thread 308fab02-e03e-4189-b24a-38895ad8a936, session feature-authority. Delegated transcript capture is blocked: scripts/agent-recorder.py cannot read T3 v2 delegated threads (statev2 orchestration tables). The lead keeps a raw export.

No user-facing UI changes; screenshots do not apply.

Rollout and rollback

Do not merge or publish as part of this task. The supplement enables nothing and the release gate is unchanged. A later full repin must reconcile these four rows with the global ledger, including the shared PublicError drift. Revert this PR to remove the supplement and its test; no API, credential, enrollment, package channel or deployment change is involved.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

Summary by CodeRabbit

• Documentation

  • Added reference documentation for feature-evaluation APIs, including schemas, authentication, validation rules, responses, rate limits, and known exclusions.
  • Documented messaging and platform evaluation, enrollment requirements, optional locale and project settings, and exposure behavior.
  • Clarified that feature-evaluation operations are not available through the TypeScript SDK.

• Tests

  • Added contract coverage validating API metadata, request and response fields, security requirements, exclusions, and documented error behavior.

• Chores

  • Added automated synchronization and validation for feature-evaluation contract snapshots.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Team
• Run ID: e21ac07a-f94d-419c-8841-671770bcc941

📥 Commits

Reviewing files that changed from the base of the PR and between d2c5b3d and e795c07.

📒 Files selected for processing: 4

• contracts/README.md
• contracts/feature-evaluation.json
• packages/typescript/test/feature-evaluation-contract.test.ts
• scripts/sync-feature-evaluation-contract.mjs

Included review availability: This review used your included allowance. 5 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 6 reviews per hour.

📝 Walkthrough

The changes add a pinned feature-evaluation API contract and a script to extract and validate its operations. Tests verify the contract and confirm that these routes remain excluded from TypeScript generation. Documentation describes the recorded API details and synchronization process.

Changes: Feature-evaluation contract

Layer / File(s)	Summary
Pinned API contract and synchronization contracts/feature-evaluation.json, scripts/sync-feature-evaluation-contract.mjs	The contract records messaging and platform feature evaluation, enrollment, and exposure operations, including schemas, authentication, responses, and TypeScript exclusion metadata. The script extracts operations from a specified revision and validates references, fingerprints, and coverage ledger entries.
Contract verification and documentation packages/typescript/test/feature-evaluation-contract.test.ts, contracts/README.md	Tests check source metadata and hashes, schemas, coverage, authentication, and the absence of typed SDK methods for these routes. The documentation describes the contract changes, credential requirements, and synchronization process.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to e795c

The pinned contract and its verification can proceed through normal checks; no issue requiring a pre-merge fix was identified.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: recording the feature availability contract from API #561.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-21T22:50:59.278467Z	e795c07	PR opened
🔒 Security Review	✅ Completed 2026-10-21T22:51:16.920653Z	e795c07	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.