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.

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:

const handlerStart = route.metadata?.handlerStart;  // undefined!

Correct:

const handlerStart = route.handlerStart;  // 93

TypeScript interfaces — define custom fields at top level:

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:

KeyWhy reserved
typeWould overwrite node type (VARIABLE, FUNCTION, etc.)
idWould overwrite semantic ID
nameWould overwrite display name
fileWould overwrite file path
exportedWould overwrite export flag
nodeTypeInternal RFDB wire field
originalIdInternal legacy field
semanticIdInternal field

Use non-colliding names:

Don't useUse instead
metadata.typemetadata.tsType
metadata.namemetadata.displayName
metadata.idmetadata.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