context-assignment

name

context-assignment

description

Use whenever a task touches context selection, scope tagging, or the ctx system UI at matrx-frontend — adding a context picker to a surface, showing per-entity context status, tagging files/notes/agents to scopes, setting the working (active) context, filtering by context, or upload-time context prompts. Triggers on features/scopes/components/context-assignment/**, active-context/**, ContextAssignmentField, ActiveContextButton, ContextStatusButton, UploadContextPrompt, appContextSlice, or any request like "add context selection to X", "tag this entity", "show context status". Read this BEFORE wiring any context UI — picking the wrong mode or writer is the

Context assignment — picking the right component

The mental model (read this or you WILL wire it wrong)

1. Membership, not ownership. A USER belongs to MULTIPLE organizations (personal workspace + any number of real orgs). Never assume one org per user, never force an org choice before showing projects/tasks — both can be org-less ("unassigned"), and that is normal, not an error.
2. The hierarchy: organization → scope types (the org's custom dimensions, e.g. Clients, Matters) → scopes (instances, e.g. "Acme Corp") → context items (typed fields per scope). Tasks may live in projects but DON'T have to; projects may live in orgs but DON'T have to.
3. A scope NEVER implies its organization. Org is an independent context dimension — it is part of a selection only when explicitly checked. Display follows the same rule (ContextSummaryChips enforces it).
4. Three runtime layers — NEVER conflate them (full table: /Users/armanisadeghi/code/common-docs/systems/scopes-context/STATE.md → "Runtime context — three layers"):
   • Layer A — Active (working/passive) context = "what I'm doing right now"; ephemeral; lives in appContextSlice; feeds every agent run automatically (execute-instance stamps it). MULTI-scope (keyed by scope id since 2026-06-12), single org/project/task, plus independent active scope types (active_scope_type_ids, 2026-06-30 — "whole dimension in play, no instance chosen"). Writers MUST be Surface A (ESLint-gated; the write actions include setActiveScopeTypes).
   • Layer B — Reference tree = what exists (org→type→scope→item). Cache only; fetched once at boot. Being consolidated onto the hierarchy owner — read scope data via hierarchy selectors, do NOT reach for the fragmented scopeTypes/scopes/… fan-out slices in new code.
   • Layer C — Durable object assignment = "this entity belongs to these"; persisted in canonical platform.associations via the setEntityScopes chokepoint, from the user's explicit UI selection. (The legacy ctx_scope_assignments table is RETIRED — FE cut over 2026-06, zero DB functions reference it; never write to or read from it.)
   • A user ACTION (Layer C) must read the explicit selection, never Layer A just because it's loaded. A successful write that sourced Layer A is worse than a failure — it silently mis-binds. Never auto-convert active → durable (suggest only). The condemned agent_surface binding service (features/surfaces) is the cautionary example of doing this wrong.

Component selection table

You need…	Use	Mode/notes
Tag an entity (file/note/agent/…) inline on a page	ContextAssignmentField	mode="assignment", pass subject; use dimensions={["scopes"]} when the surface is scope-only (no project/task FK intent)
Same, without blocking the page	ContextAssignmentPopover	trigger = your button
Same, as an explicit modal step	ContextAssignmentDialog	controlled open
Same, floating/draggable	ContextAssignmentWindow	inline-controlled
Set the WORKING context from a header/toolbar	ActiveContextButton	live-apply popover; sizes xs/sm, iconOnly for rails
Same field inside a tab panel / drawer (no trigger)	ActiveContextPanel	composes ContextAssignmentField mode="active"; default checkboxVariant="standard"; used by RunControlsMenu Context tab
Clear working context (rose Eraser + "Context", app-wide)	ClearContextButton	dispatches clearContext; wired into every Surface A control
Show context status per entity (amber/green nudge)	ContextStatusButton	pass knownScopeCount on list rows (bulk!), omit on single-entity surfaces
Display a selection readably	ContextSummaryChips	compact chips for headers; org only if explicit
Labeled active/filter breakdown in the field footer	ContextSelectionSummary	Org · Scope Types (group) · per-type scopes · Projects · Tasks
Prompt for context during an upload	UploadContextPrompt	Save awaits awaitFileIds() — handles both races
Filter a list by context (no saving!)	ContextAssignmentField mode="filter"

All in features/scopes/components/context-assignment/ except ActiveContextButton + ActiveContextPanel (features/scopes/components/active-context/ — Surface A writers MUST live there; ESLint + FEATURE.md enforce it).

Hard rules

• Fetch discipline. The org/type/scope tree is fetched ONCE at boot into Redux (ensureScopeTree → state.scopesTree) and refreshed only by scopeTreeInvalidationMiddleware on structural mutations. Components NEVER refetch it. It is durably warm-cached across hard reload by the sync engine (scopesTreePolicy in features/scopes/redux/scopesSlice.ts): a warm boot rehydrates the tree before paint and ensureScopeTree() skips the network entirely (no staleAfter/remote.fetch — the tree changes rarely). Projects/tasks/items go through context-assignment/data.ts (60s TTL + in-flight dedup). List surfaces use getEntityScopesBulk/primeEntityScopes — N rows must never mean N requests. Add new reads to data.ts, never to a component.
• Write paths. Scopes → useEntityScopes().setScopes / setEntityScopes thunk only. Active context → dispatch from active-context/ components only. Entity FKs (e.g. a note's project_id) → that feature's save pipeline, applied from onSaved's selection (see features/notes/components/NoteContextSection.tsx as the template).
• Dimension gating. Pass dimensions={["scopes"]} (or any subset of "scopes" | "projects" | "tasks") to hide sections that do not apply — e.g. project settings (scope tagging only) vs notes (scopes + project/task FK intent). Default is all three. Org dropdown (assignment) and org rows (active/filter) are independent of dimensions.
• Org default-but-changeable. Assignment mode defaults to "All organizations" (ALL_ORGS sentinel — nothing filtered, scope sections grouped per org, selection.organizationId = null). Surfaces that "enforce" an org pass defaultOrganizationId to override that default; the user can always switch (including back to All).
• No layout shift. Fixed section heights; fixed-size check targets; status icons swap glyphs, never dimensions.
• Mobile = one bottom sheet. Every wrapper (ContextAssignmentPopover, ContextAssignmentDialog, ContextAssignmentWindow, UploadContextPrompt, ) switches to on — never a desktop popover/dialog/window on a phone. (built on the primitive) hosts the body with , which makes the field's own section list the single scroll area and pins the footer. Never set a fixed inside a sheet (that re-introduces nested scrolling) — pass instead. The field's org-of-record row stacks () so it never overflows a narrow screen.

Live references

• Design surface / every variant demoed: /demos/scopes/context-lab (app/(dev)/demos/scopes/context-lab/page.dev.tsx).
• Real integrations to copy from: files table cell (features/files/components/surfaces/desktop/FileContextCell.tsx), upload prompt host (features/files/components/surfaces/PageShell.tsx), note adapter (NoteContextSection.tsx), header button (ChatRunHeader.tsx), run-controls tab (RunControlsMenu.tsx Context tab → ActiveContextPanel).
• Current state: features/scopes/FEATURE.md (the live SOR for scope/context on the FE).
• Historical architecture plan (superseded, shipped as platform.associations): docs/archive/2026/ctx/ctx-association-architecture.md.