epic-3/story-2: Support Mutable Visitor State on Contexts by usmanabbas7 · Pull Request #34 · convertcom/python-sdk

usmanabbas7 · 2026-06-08T08:14:11Z

Story 3.2: Support Mutable Visitor State on Contexts

Part of sprint sprint/2026-04-06-convert-python-sdk. Stacked on epic-3/story-1 (#33 → #32 → #31 → #30 → #29 → #24).

Adds the public Context.set_attributes(attributes: dict[str, Any]) -> None mutation surface on top of the Story 1.3 Context/ContextState foundation and the Story 3.1 DataStore persistence boundary. Honors audit finding F-008.

What was built

domain/context_state.py — immutable ContextState.with_attributes(...) returning a merged copy (frozen, L0-clean; no in-place mutation).
context.py — Context.set_attributes(...) rebinds ContextState to the merged copy and persists it through the injected DataStore (_persist_visitor_state()); request-time overlay seam (_resolve_visitor_attributes) left unchanged and distinct (overlay > persisted-state precedence).
core.py — create_context now hydrates per-visitor ContextState from the store (_hydrate_visitor_attributes) and injects the single per-Core DataStore into the context seam, so a fresh create_context(visitor_id) rehydrates the persisted update (AC#3).
ports/storage.py — added stable visitor-scoped visitor_state_key() (mirrors the dedup: namespacing); no second store, no parallel dict, no second key scheme.
JS parity = Context.updateVisitorProperties → _dataManager.putData(visitorId, {segments}) (F-008-corrected anchor).

Audit finding honored

F-008 — update applies by replacing ContextState with a merged copy persisted through the DataStore (corrected from the stale getVisitorProperties-only deep-merge framing). Baked into the spec; verified in code.

Driver-resolved precedence (auto-delegated, sprint mode)

Story 3.1 did NOT actually wire ContextState hydrate/save in create_context (only tracking/deduplication.py used the store) — minimal hydrate/save wiring added through the SAME single per-Core DataStore and a new state:<visitor_id> key. Logged as a "your call" auto-delegation.
The stale "working tree effectively empty" story note was ignored; full shipped 1.1–3.1 code was extended.
Layering enforced via the existing static-scan tests/test_layering.py (import-linter not installed in MVP toolchain); context.py depends only on the ports/storage.py protocol.

Beads

Epic ai-driven-product-dev-u4mw; tasks -vi7i, -ni5e, -xuci — all closed.

Tests

396 → 415 (+19), zero regressions. Extended flat tests/test_context_creation.py (unit) + tests/integration/test_in_memory_store.py (qs-06 round-trip).

Sprint-mode notes

Readiness gate: PASS 8.6/10, 3 questions auto-delegated ("your call"). See conductor's work/2026-06-08-support-mutable-visitor-state-on-contexts/readiness-assessment.md.
Code review: clean, 1 round, no warnings.

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request implements mutable visitor state persistence (Story 3.2) by introducing Context.set_attributes() to persistently update and merge visitor attributes via an injected DataStore, and rehydrating these attributes during context creation in Core. The review feedback suggests several performance and API flexibility improvements: typing the attributes parameter as Mapping[str, Any] instead of dict[str, Any] for better flexibility, and avoiding unnecessary dictionary copying/object instantiation in ContextState.with_attributes() and Core._hydrate_visitor_attributes() when no new attributes are provided.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-08T08:15:30Z


+    # --- mutable visitor state (Story 3.2) ---------------------------------
+
+    def set_attributes(self, attributes: dict[str, Any]) -> None:


Using Mapping[str, Any] instead of dict[str, Any] for the attributes parameter is more Pythonic and flexible. It allows callers to pass other mapping types (such as MappingProxyType or custom read-only dictionaries) and aligns with the type hints used elsewhere in the SDK (e.g., visitor_attributes is typed as Optional[Mapping[str, Any]]).

Suggested change

def set_attributes(self, attributes: dict[str, Any]) -> None:

def set_attributes(self, attributes: Mapping[str, Any]) -> None:

gemini-code-assist · 2026-06-08T08:15:30Z

+        merged = dict(self.visitor_attributes)
+        if new_attributes:
+            merged.update(new_attributes)
+        return ContextState(
+            visitor_id=self.visitor_id,
+            snapshot=self.snapshot,
+            visitor_attributes=merged,
+        )


If new_attributes is empty or None, we can return self directly. Since ContextState is a frozen dataclass, returning self is perfectly safe, avoids unnecessary dictionary copying, and prevents creating a new ContextState instance.

Suggested change

merged = dict(self.visitor_attributes)

if new_attributes:

merged.update(new_attributes)

return ContextState(

visitor_id=self.visitor_id,

snapshot=self.snapshot,

visitor_attributes=merged,

)

if not new_attributes:

return self

merged = dict(self.visitor_attributes)

merged.update(new_attributes)

return ContextState(

visitor_id=self.visitor_id,

snapshot=self.snapshot,

visitor_attributes=merged,

)

gemini-code-assist · 2026-06-08T08:15:30Z

+        merged = dict(stored)
+        if visitor_attributes:
+            merged.update(visitor_attributes)
+        return merged


If visitor_attributes is empty or None, we can return stored directly. This avoids an unnecessary dictionary copy when there are no caller-supplied attributes to merge with the persisted state.

Suggested change

merged = dict(stored)

if visitor_attributes:

merged.update(visitor_attributes)

return merged

if not visitor_attributes:

return stored

merged = dict(stored)

merged.update(visitor_attributes)

return merged

…ibutes — tests (RED) Beads: ai-driven-product-dev-vi7i Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ibutes — implementation (GREEN) Beads: ai-driven-product-dev-vi7i Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…RED) Beads: ai-driven-product-dev-ni5e Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…_context — implementation (GREEN) Beads: ai-driven-product-dev-ni5e Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…n round-trip — tests (verification) Beads: ai-driven-product-dev-xuci Verification task (Task 4): no production code change; proves FR25 determinism, AC#5 overlay/persisted distinction, AC#2/#3 round-trip via qs-06 fixture. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

abbaseya · 2026-06-18T16:31:26Z

Superseded — all commits already in main (bc76b64). Closing without merge as part of post-sprint cleanup.

usmanabbas7 self-assigned this Jun 8, 2026

usmanabbas7 requested a review from clllaur June 8, 2026 08:14

gemini-code-assist Bot reviewed Jun 8, 2026

View reviewed changes

usmanabbas7 and others added 5 commits June 14, 2026 21:59

wf(wf-3p2sm): [SDK-1] ContextState.with_attributes + Context.set_attr…

4031ef8

…ibutes — tests (RED) Beads: ai-driven-product-dev-vi7i Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(wf-3p2sm): [SDK-1] ContextState.with_attributes + Context.set_attr…

f57b16c

…ibutes — implementation (GREEN) Beads: ai-driven-product-dev-vi7i Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(wf-3p2sm): [SDK-2] persist-through-DataStore + rehydrate — tests (…

bd25c28

…RED) Beads: ai-driven-product-dev-ni5e Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

wf(wf-3p2sm): [SDK-2] persist-through-DataStore + rehydrate on create…

ce3034f

…_context — implementation (GREEN) Beads: ai-driven-product-dev-ni5e Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

usmanabbas7 force-pushed the epic-3/story-1-add-the-persistence-boundary-and-in-memory-store branch from c413d52 to 52f5a08 Compare June 14, 2026 16:59

usmanabbas7 force-pushed the epic-3/story-2-support-mutable-visitor-state-on-contexts branch from c9d9d13 to 2298a37 Compare June 14, 2026 16:59

abbaseya closed this Jun 18, 2026

abbaseya deleted the epic-3/story-2-support-mutable-visitor-state-on-contexts branch June 18, 2026 16:31

Navigation Menu

Uh oh!

epic-3/story-2: Support Mutable Visitor State on Contexts - #34

epic-3/story-2: Support Mutable Visitor State on Contexts#34
usmanabbas7 wants to merge 5 commits into
epic-3/story-1-add-the-persistence-boundary-and-in-memory-storefrom
epic-3/story-2-support-mutable-visitor-state-on-contexts

usmanabbas7 commented Jun 8, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		# --- mutable visitor state (Story 3.2) ---------------------------------

		def set_attributes(self, attributes: dict[str, Any]) -> None:

	def set_attributes(self, attributes: dict[str, Any]) -> None:
	def set_attributes(self, attributes: Mapping[str, Any]) -> None:

Uh oh!

Conversation

usmanabbas7 commented Jun 8, 2026

Story 3.2: Support Mutable Visitor State on Contexts

What was built

Audit finding honored

Driver-resolved precedence (auto-delegated, sprint mode)

Beads

Tests

Sprint-mode notes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants