Skip to content

Disentinel/grafema / .claude/skills/grafema-metadata-flattening

rfdb-metadata-gotchas

Verified

Fix silent metadata issues in RFDB node storage. Covers two traps: (1) metadata flattening — nested metadata fields become top-level after serialization, so node.metadata.field is undefined but node.field works. (2) reserved keys — fields named "type", "id", "name", "file", "exported" are silently stripped from metadata by _parseNode() to prevent overwriting top-level node fields.

FileKindSize
SKILL.mdskill md2.5 KB
---
name: rfdb-metadata-gotchas
description: |
  Fix silent metadata issues in RFDB node storage. Covers two traps:
  (1) metadata flattening — nested metadata fields become top-level after
  serialization, so node.metadata.field is undefined but node.field works.
  (2) reserved keys — fields named "type", "id", "name", "file", "exported"
  are silently stripped from metadata by _parseNode() to prevent overwriting
  top-level node fields.
author: Claude Code
version: 2.0.0
date: 2026-05-03
---

# RFDB Metadata Gotchas

## Trap 1: Metadata Flattening

RFDB serialization flattens nested metadata to the node's top level.

**What happens:**
1. Analyzer stores: `{id, type, file, metadata: {handlerStart: 93}}`
2. `client.addNodes` serializes metadata as JSON string
3. `_parseNode` deserializes and spreads onto top level
4. After retrieval: `handlerStart` is at TOP LEVEL, not nested

**Wrong:**
```typescript
const handlerStart = route.metadata?.handlerStart;  // undefined!
```

**Correct:**
```typescript
const handlerStart = route.handlerStart;  // 93
```

**TypeScript interfaces** — define custom fields at top level:
```typescript
interface HttpRouteNode extends BaseNodeRecord {
  type: 'http:route';
  handlerStart?: number;  // top level, not nested under metadata
}
```

## Trap 2: Reserved Keys (Silent Data Loss)

`_parseNode()` strips these keys from metadata to prevent overwriting top-level node fields:

| Key | Why reserved |
|-----|-------------|
| `type` | Would overwrite node type (VARIABLE, FUNCTION, etc.) |
| `id` | Would overwrite semantic ID |
| `name` | Would overwrite display name |
| `file` | Would overwrite file path |
| `exported` | Would overwrite export flag |
| `nodeType` | Internal RFDB wire field |
| `originalId` | Internal legacy field |
| `semanticId` | Internal field |

**Use non-colliding names:**

| Don't use | Use instead |
|-----------|-------------|
| `metadata.type` | `metadata.tsType` |
| `metadata.name` | `metadata.displayName` |
| `metadata.id` | `metadata.externalId` |

## Detection

1. `console.log(JSON.stringify(node, null, 2))` — check if field is at top level
2. Raw wire format: `backend._client.getAllNodes()` returns `WireNode` with metadata as JSON string
3. If field appears in raw wire but not in parsed node → reserved key stripping

## Notes

- Applies to ALL custom fields on nodes, not just metadata
- Both TestDatabaseBackend and RFDBServerBackend have this behavior
- If you need truly nested data, store it as a JSON string that doesn't get auto-parsed
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall