Disentinel/grafema / .claude/skills/grafema-metadata-flattening
rfdb-metadata-gotchas
VerifiedFix 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.5 KB |
SKILL.md
View on GitHub---
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |