Implement an immutable SDK request context with scoped metadata propagation

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): backend, type-safety, consistency, expert

Background

As the GuildPass SDK grows, individual operations may need to carry scoped metadata such as request identifiers, caller tags, tracing values, or diagnostic attributes through internal layers.

Passing mutable plain objects through many functions can create hidden coupling and accidental mutation.

This issue introduces a generic immutable request-context primitive without integrating it into transport or client methods.

Problem

There is currently no standard SDK mechanism for safely propagating scoped metadata through nested operations.

A mutable context object can be changed by one internal function and unexpectedly affect unrelated callers or sibling operations.

Expected Outcome

Implement an immutable request context that supports typed metadata lookup, derivation, and controlled propagation.

Suggested Implementation

The design may include APIs conceptually similar to:

const child = context.with("requestId", "req_123");
const value = child.get("requestId");

A stronger typed-key design is preferred over an unrestricted global string dictionary if practical.

The context should:

• support creation of an empty context;
• support deriving a new context with additional metadata;
• leave the parent unchanged;
• support retrieving values by key;
• distinguish an absent key from a key storing undefined if undefined is supported;
• support nested derivation efficiently;
• prevent callers from mutating internal stored values through exposed collections where practical;
• optionally support removal or shadowing semantics if clearly documented;
• provide deterministic conversion to safe diagnostic metadata for primitive values;
• avoid relying on AsyncLocalStorage or global process state;
• remain generic and framework-independent.

Acceptance Criteria

• Empty contexts can be created.
• Derived contexts inherit parent values.
• Parent contexts remain unchanged after derivation.
• Child values can shadow parent values according to documented semantics.
• Independent branches derived from the same parent do not affect each other.
• Missing-key behaviour is explicit.
• Internal maps or collections are not exposed mutably.
• Deep derivation chains behave correctly.
• Unit tests cover inheritance, shadowing, sibling isolation, and immutability.
• Type-level tests or compile-time examples demonstrate safe typed-key usage if implemented.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No transport integration, AsyncLocalStorage, or global context management is introduced.

Likely Affected Files/Directories

src/context/ or equivalent focused module
src/types/
tests/

Independence Requirement

This issue must be independently implementable from the current SDK baseline and must not depend on middleware, diagnostics, or transport contributions.

[Prz-droid]

GM Maintainer, I’d like to take on this expert-level issue. I have experience building type-safe TypeScript SDKs and designing immutable data structures, and I’ll implement a generic request-context primitive with typed key support, efficient immutable derivation, inheritance, shadowing, and clear missing-key semantics. I’ll ensure parent contexts and sibling branches remain isolated, prevent mutable access to internal state, and document the chosen API and semantics. I’ll also add comprehensive unit and type-level tests covering deep derivation and immutability, then verify everything with pnpm typecheck, pnpm build, and pnpm test while keeping the implementation completely independent of transport, AsyncLocalStorage, and global state
ETA: 24hrs

[Akinyemi04]

i have experience working on issues such as this... i'll like to work on this issue

[JuliobaCR]

Hi @Lakes41 👋 I'd like to work on this issue.

Problem

The SDK has no standard mechanism for safely propagating scoped metadata (request IDs, caller tags, tracing values) through nested internal operations. Passing mutable plain objects around creates hidden coupling — one function can mutate a context and unexpectedly affect unrelated sibling calls.

Proposed Solution

• Implement a generic, immutable request-context primitive: context.with("key", value) derives a new child context without touching the parent, and child.get("key") retrieves typed values.
• Support: empty-context creation, derivation that inherits parent values while leaving the parent unchanged, shadowing of parent keys with documented semantics, sibling branches that stay fully isolated from each other, and an explicit (not silently-undefined) distinction between "key absent" and "key set to undefined."
• Prefer a typed-key design over an unrestricted string dictionary where practical, and avoid exposing internal maps/collections in a mutable way.
• No AsyncLocalStorage, no global process state, no transport/middleware integration — this stays a framework-independent primitive per the issue's independence requirement.
• Tests covering inheritance, shadowing, sibling isolation, deep derivation chains, and immutability; type-level/compile-time examples if a typed-key design is implemented.
• Verify with pnpm typecheck, pnpm build, pnpm test.

Estimated time: 1–2 days, mostly test coverage for the isolation and shadowing edge cases.

Happy to coordinate here if useful — let me know if I should proceed.

[ayaanoncrypto]

I’ve worked with type-safe TypeScript SDKs and immutable data structures. I’ll add a framework-independent RequestContext with typed keys, immutable derivation, inheritance, documented shadowing, explicit missing-key behavior, and safe diagnostic serialization for primitive values. Parent contexts and sibling branches will remain isolated, with no transport integration, AsyncLocalStorage, or global state. I’ll add unit and type-level coverage for deep derivation, immutability, shadowing, sibling isolation, and undefined handling. Please assign me 🥺

[EmmyKay0026]

Hello there, I came across your project and will love the opportunity to work on it. I would complete it promptly and without conflicts

[grantfox-oss]

🦊 GrantFox — @Prz-droid has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #467)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.