WORK-269
ID:WORK-269Status:done

embed() embeddability contract

Generalize SPEC-066's sourceFile + extract into the embed() contract: an entity is embeddable if it has embed() or (sourceFile + extract). expand and the entityRoutes adapter accept either, so external plugins can make entities embeddable without a source file on disk.

Priority:mediumComplexity:moderateMilestone:v0.16.0Source:SPEC-069
claude/v0.16.0 View source

Criteria completion

Criteria completion: 0 of 4 (0%) checked; tracking started on May 25, no incremental history yet0%25%50%75%100%May 25Jun 15

Tracking started May 25 — check back for trends.

Relationships

Implements 1
Branches 2
claude/v0.16.0 current done
claude/milestone-v0.16.0 readymain ready
History 2
  1. 020ab26
    Created (done)by bjornolofandersson
  2. 7ab7615
    Content editedby Claude
    plan: add v0.16.0 milestone and work breakdown for SPEC-069/070/071

Acceptance Criteria

  • An entity is embeddable if it has embed() or (sourceFile + extract); expand resolves both forms
  • embed() returns the entity's renderable subtree (or source) for inlining
  • Entities with neither produce a clear build error when expanded, naming the entity
  • The existing plan expand path (sourceFile + extract, from v0.15.0) continues to work unchanged

Dependencies

None — extends the existing expand/embeddability machinery; WORK-270 uses it for plan entities.

References

  • SPEC-069

Resolution

Completed: 2026-05-25

Branch: claude/v0.16.0

What was done

  • EntityRegistration.embed?: () => Node | null added to the contract (SPEC-069): returns the entity's embeddable AST directly, no file read.
  • expand-pipeline.ts: embeddability check is now embed() || (sourceFile && extract); resolution prefers embed() (no projectRoot needed), else reads + extracts from sourceFile; clear error when neither is present.
  • Test: added an embed()-without-source-file case to packages/runes/test/expand-pipeline.test.ts (19 green); the existing file-backed path (sourceFile+extract) is unchanged.

Notes

  • Enables external plugins (Jira/Notion/etc.) to make entities embeddable without a file on disk. The plan plugin keeps using sourceFile+extract (WORK-270 sets those).