code-flow-scope-colors

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Flow Scope Colors

## Mandatory Output Rule

**Every response using this skill MUST:**

1. Begin with an **Adapted Scope Palette** (only colors used in this flow).
2. Include **abstract assignment blocks** (`coloredField = expr`, gates, scope open/close) for the
   whole flow — not only timestamp or oplog sections.
3. End with the **Invariant Prompt**.

Do not dump the full canonical palette unless all nine colors appear. Never assign a color without
saying what scope it denotes. Never explain a flow with call names and arrows alone.

## Core Rule

Color by **owning scope / lifetime**, not by function name or call site.

**Diagrams are abstract assignment code**, not narrated call graphs. Show what gets stored where,
with `=` for every mutation or scope crossing. Use `->` only for sequencing (open WUOW, then
commit), never as a substitute for `dest = source`.

**Do not color a function call** unless you are naming the scope it establishes. Prefer the state
the call creates:

```text
// Wrong
⚪ acquireCollection() -> applyOperation_inlock()

// Right
🟢 TransactionResources += CollectionAcquisition request   // extends 🟢 opCtx bundle
⚪ collHandle = view into 🟢 TransactionResources           // stack-local ref
```

## Canonical Scope Palette

Reference definitions. Copy only the entries you use into the Adapted Scope Palette and adjust
wording when the flow needs a sharper label.

```text
⚫ black  = durable/on-disk state
           RecordStore bytes, SortedDataInterface entries, _mdb_catalog records,
           durable oplog records, persisted config collections.

🔴 red    = in-memory catalog / metadata view
           CollectionCatalog, IndexCatalog, IndexCatalogEntry, CollectionPtr metadata,
           in-memory multikey state, in-memory routing-independent catalog metadata.

🟡 yellow = oplog / replicated payload
           OplogEntry, DurableOplogEntry, applyOps payload, prepare/commit oplog entries,
           op.timestamp, op.object, op.nss, op.uuid.

🟢 green  = OperationContext scope and opCtx decorations
           MultikeyPathTracker, Locker, CurOp, RecoveryUnit access through opCtx,
           TransactionResources, OperationShardingState, request-local state
           attached to the current operation.

🟠 orange = ServiceContext / process-global service scope and decorations
           StorageEngine, ReplicationCoordinator, OpObserver, global services,
           server-wide feature flags, failpoints, service-level registries,
           CursorManager stashed resources.

⚪ white  = WriteUnitOfWork / local lexical scope
           WUOW lifetime, variables created inside the WUOW, rollback hooks,
           scoped guards, stack-local temporaries, per-WUOW derived state.
           NOT opCtx decorations, NOT acquisition handles, NOT API entry points.

🟣 purple = RecoveryUnit / storage transaction in-memory state
           RU timestamp, commit timestamp, prepare timestamp, snapshot state,
           WiredTiger transaction state before durability.

🟤 brown  = routing / sharding / placement metadata
           ShardVersion, DatabaseVersion, ChunkManager, CatalogCache,
           placement info, routing table state, ownership filter, RangePreserver.

🔵 blue   = client request / command payload before it becomes oplog
           InsertCommandRequest, UpdateRequest, DeleteRequest, parsed command,
           query specs, update specs, router-attached version fields.
```

## Adapted Scope Palette

Build this at the top of every response. Include only colors used below. Extend or narrow canonical
definitions when the flow requires it.

Example for shard-role acquisition:

```text
Adapted palette (shard role acquisition):

🔵  Incoming command + router-attached ShardVersion / DatabaseVersion
🟢  OperationContext decorations: OperationShardingState, TransactionResources,
    locks; CollectionAcquisition is a ref-counted view into this scope
🔴  In-memory local catalog snapshot: CollectionCatalog, CollectionPtr
🟤  Sharding placement: PlacementConcern, ownership filter, RangePreserver
🟣  Storage snapshot opened to match the catalog read
⚫  Durable bytes read/written through the pinned catalog view
⚪  WriteUnitOfWork wrapping individual document writes (separate from acquisition)
```

## Assignment & Scope-Change Notation (mandatory — all flows)

**Every diagram** for any topic (oplog, yield, acquisition, multikey, sharding, commands) must use
this notation. Specialized sections below are **templates**, not exceptions.

### Required elements

| Element           | Syntax                                           | When                                                |
| ----------------- | ------------------------------------------------ | --------------------------------------------------- |
| Copy / promote    | `🟢 dst = 🟡 src`                                | Value crosses scope; recolor on RHS if type changes |
| In-place mutate   | `🔴 entry.flags \|= MULTIKEY`                    | Field updated inside same scope                     |
| Gate              | `canX = false — because <scope condition>`       | Branch chooses which assignments run                |
| Conditional write | `if canX: 🟣 field = expr`                       | Write may be skipped; say who owns it when false    |
| Scope open        | `⚪ wuow = WriteUnitOfWork { open }`             | New lexical lifetime                                |
| Scope close       | `⚪ wuow.commit()` / `destroy`                   | End lifetime; show what 🟣/⚫ gains                 |
| Detach            | `⚪ bundle = 🟢 resources; 🟢 resources = empty` | Ownership leaves opCtx                              |
| Attach            | `🟢 resources = ⚪ bundle`                       | Restore                                             |
| Derive            | `🟡 subOpᵢ = extract(🟡 parent)`                 | New objects in same or new scope                    |
| Invalidate        | `🔴 CollectionPtr = UNSAFE`                      | Handle outlives valid view                          |

From enricogolfieri/workspace-mongo, Unlicense.

More from enricogolfieri/workspace-mongo