attach-primitive
Installation
SKILL.md
Attach Primitives
Every persistence, sync, materializer, and binding in packages/workspace (plus session-shaped primitives in packages/cli) follows one shape. Match the invariants exactly.
Naming
| Prefix | Meaning |
|---|---|
attach* |
Side-effectful. Registers observers, destroy listeners, or subscription state onto a subject argument. Returns a plain object whose surface is fixed at call time. |
create* |
Pure construction OR module-singleton bootstrap. No subject argument. Cache constructors qualify (e.g. createFileContentDocs returns a createDisposableCache result; nothing attaches until .open(id) is called). Module-singleton factories that bootstrap themselves at construction time (e.g. createManualRecorder registering a global event listener) also use create*: the side effects belong to the singleton itself, not to an external subject. |
Both return plain objects. The distinction is whether the call modifies a subject argument, not just whether side effects fire at call time.
Scope of this contract
These rules apply to packages/workspace primitives and other functions that take a subject (a Y.Doc, an attachment, or a comparable composable target) and decorate it. They do not apply to:
- Module-level factory singletons in app code (e.g. UI state containers, service clients) — even if those factories perform I/O at construction time. Use
create*. - Top-level orchestrators that own their own lifecycle and aren't attached to anything external.