無料GitHub で公開

rfdb-metadata-gotchas

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.

Disentinel/grafema

インストール方法を見る

含まれるファイル（1）

SKILL.md2.5 KB

SKILL.md（原文）

インストールする前に、エージェントに与えられる指示の中身を確認できます。

RFDB Metadata Gotchas

Trap 1: Metadata Flattening

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

What happens:

Analyzer stores: {id, type, file, metadata: {handlerStart: 93}}
client.addNodes serializes metadata as JSON string
_parseNode deserializes and spreads onto top level
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:

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

console.log(JSON.stringify(node, null, 2)) — check if field is at top level
Raw wire format: backend._client.getAllNodes() returns WireNode with metadata as JSON string
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

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

ログインしてレビューを書く

同じリポジトリのスキル

概要と使いどころ

beam-elixir-ast-gotchas

無料

Fix Elixir/Erlang AST processing bugs in Grafema beam-analyzer. Use when: (1) Elixir parser returns MODULE node but 0 functions/calls — body nesting issue, (2) Erlang parser crashes with "cannot convert list to string" on OTP 26+ — location format changed from integer to keyword list, (3) pipe operator |> creates spurious CALL nodes instead of desugared function calls — clause ordering bug, (4) multi-module .ex files return only the first module — missing __block__ handler, (5) installing Erlang/Elixir on macOS with outdated Xcode/Clang.

日本語の概要は準備中です。原文の説明を表示しています。