[codex] Structure client state key errors

[juliusmarminge]

Summary

• replace generic project/thread atom-key failures with distinct Schema-tagged errors carrying malformed keys
• validate project-reference and asset-collection keys while preserving exact native JSON or Schema causes
• reuse the shared thread-key parser in environment thread atoms instead of maintaining a duplicate raw-error path

Validation

• pnpm vp test packages/client-runtime/src/state/assets.test.ts packages/client-runtime/src/state/entities.test.ts packages/client-runtime/src/state/threads-atoms.test.ts
• pnpm vp check (20 pre-existing warnings)
• pnpm vp run typecheck

No active open PR modifies these files.

---

Note

Low Risk
Localized error-handling and key parsing in client state atoms; behavior on valid keys is unchanged and failures become more explicit rather than riskier.

Overview
Client-runtime atom family keys now fail with typed, inspectable errors instead of generic Error or unchecked JSON.parse casts.

In entities.ts, parseProjectKey and parseThreadKey throw distinct tagged errors that include the malformed key; parseProjectRefCollectionKey validates JSON as an array of [string, string] tuples and wraps parse/decode failures with the original cause. assets.ts adds the same pattern for asset collection keys (EnvironmentId + AssetResource[]) via parseAssetCollectionKey and InvalidAssetCollectionKeyError.

threads.ts drops its duplicate thread-key helpers and uses shared threadKey / parseThreadKey from entities.ts. New unit tests cover malformed keys, invalid shapes, and preserved causes for assets and scoped entity keys.

^{Reviewed by Cursor Bugbot for commit 6274e96. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic errors with structured tagged error classes for client state key parsing

• Introduces InvalidAssetCollectionKeyError, InvalidScopedProjectKeyError, InvalidScopedThreadKeyError, and InvalidScopedProjectRefCollectionKeyError as Schema.TaggedErrorClass instances, each carrying the offending key and underlying cause.
• Adds parseAssetCollectionKey, parseProjectKey, parseThreadKey, and parseProjectRefCollectionKey utilities that validate key shape via effect/Schema and throw the appropriate structured error on failure.
• Updates createAssetEnvironmentAtoms and createEnvironmentThreadStateAtoms to use these shared parse utilities instead of inline JSON.parse calls.
• Behavioral Change: callers that previously caught generic Error on malformed keys will now receive typed tagged errors with structured fields.

^{Macroscope summarized 6274e96.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. 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: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ae9beceb-58a4-4551-ab44-38a46c885f43

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/client-state-key-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR replaces generic error throws with structured error classes for better debugging, adds Schema validation for key parsing, removes duplicate code, and includes comprehensive tests. The changes only affect error paths and don't alter happy-path runtime behavior.

^{You can customize Macroscope's approvability policy. Learn more.}