| name | workspace-api |
| description | Epicenter workspace API patterns: `defineTable`, `defineKv`, migrations, actions, `createWorkspace`, materializers, `openCollaboration`, and workspace connections. Use when editing workspace schemas, table/KV access, actions, attachments, or collaboration setup. |
| metadata | {"author":"epicenter","version":"8.0"} |
Workspace API
Use this skill for Epicenter workspace definitions, table and KV access, inline action registries, attachment composition, collaboration setup, and workspace connections.
Reference Repositories
- Yjs: CRDT framework used by the workspace data layer
- Yjs Protocols: sync, awareness, and protocol helpers used around collaboration
Upstream Grounding
When workspace behavior depends on Yjs transactions, shared types, update encoding, document lifecycle, or conflict semantics, use source-backed grounding before relying on memory. If DeepWiki MCP is available, ask a narrow question against yjs/yjs; for collaboration sync or awareness protocol behavior, ask against yjs/y-protocols. If DeepWiki is unavailable or the repo is not indexed, use upstream source or official docs directly. Treat DeepWiki as orientation, then verify decisive details against local workspace code, installed types, tests, or official docs before changing code.
Skip DeepWiki for Epicenter schema, action, migration, and attachment conventions already documented below.
Related Skills
yjs: Yjs CRDT patterns and shared types
svelte: reactive wrappers such as fromTable and fromKv, plus commit-on-blur workspace inputs
attach-primitive: the full contract and invariants every attach* function must follow
typebox: TypeBox primitives used by field.*, defineKv, and action input schemas
When To Apply This Skill
Use this skill when you are:
- Defining a table or KV store with
defineTable() or defineKv().
- Adding a version or migration to an existing table definition.
- Reading, writing, or observing table or KV data.
- Creating actions with
defineMutation or defineQuery.
- Composing a live document with
createWorkspace and surrounding attach* primitives (persistence, sync, materializers).
- Adding
createDisposableCache(builder) for per-row or fan-out documents.
- Attaching persistence, collaboration, or materializers around a workspace.
- Writing server-side Bun scripts with
connectWorkspace().
Core Rules
- Workspace action
defineQuery / defineMutation factories are not Whispering $lib/rpc adapters from wellcrafted/query. Do not apply workspace action input-schema rules to Whispering RPC modules.
_v is library-managed. Never declare it as a column, never set it on a write, never read it off a row. Single-version tables drop the versioning surface entirely; multi-version tables expose it only inside the migrate function as ({ value, version }).
- Columns are TypeBox schemas. Prefer the
field.* builders from @epicenter/field (field.string, field.number, field.boolean, field.select, field.json, field.datetime) plus the standalone nullable wrapper from @epicenter/workspace for the emptiness axis (an IANA timezone is just field.string<IanaTimeZone>(), no bespoke builder); raw Type.X() is allowed and the FlatJsonTSchema constraint enforces SQLite-mappable shapes either way.
- Derive row types with
InferTableRow<typeof tableDefinition> in the same module that defines the table. Consumers import the type from the workspace definition module.
- Do not re-derive row types from runtime table methods or relay them through state files.
- KV stores use
defineKv(schema, defaultValue) where defaultValue is a factory () => Static<S>. Prefer one scalar per dot-namespaced key unless the value is a true atomic object.
- Every table
id and string foreign key uses a branded type plus a co-located generator. The brand lives as a pure type alias (type X = string & Brand<'X'>); the generator uses generateId<X>(). Call sites use the generator, never a direct cast.
- Put isomorphic actions directly on the returned workspace as
actions: defineActions({ ... }) inside create<App>Workspace(). Avoid a separate const actions unless the same registry must be passed to another owner before return. Extract createXActions(workspace) only when the action set is shared, large enough to earn a file, or owns a real invariant. Runtime-specific actions live in the runtime builder where browser, Node, Tauri, or extension APIs are in scope.
- Construct a workspace with
createWorkspace({ id, tables, kv }) (or a per-app wrapper like createHoneycrispWorkspace). The bundle exposes { ydoc, tables, kv, [Symbol.dispose] } and using workspace cascades disposal to every store. Only the three materializers (attachBunSqliteMaterializer, attachTursoMaterializer, attachMarkdownMaterializer) take the bundle; persistence, log, and sync primitives take workspace.ydoc.
- Local action calls see the handler shape directly. Remote dispatch wraps raw values and failures in
Promise<Result<T, DispatchError>>. Read the action return reference before changing handler failure behavior.
- Every action method inside the workspace action object should have JSDoc that adds developer-facing value beyond the short
description field.
- Keep workspace schema and inline actions isomorphic. If an action file is extracted, it must stay isomorphic too. Keep
client.ts runtime-specific and outside the workspace/ folder.
- Compose attachments inline in the builder after calling
createWorkspace. Avoid wrapper helpers that hide ordering unless the abstraction owns a real invariant.
- Use
connectWorkspace() for one-off Bun scripts that need a connected workspace without app UI bootstrapping.
Reference Map
- Schema definition patterns:
defineTable, defineKv, row type inference, KV scalar design, and branded IDs.
- Actions, layout, and attachments: inline actions, JSDoc, workspace file layout, attachment ordering, and
connectWorkspace.
- Deriving action input schemas: use
tables.X.schema and schema.properties.X to compose defineQuery/defineMutation input schemas inline. No helper layer.
- Action return shapes: local vs remote action return contracts and error normalization.
- Table, KV, CRUD, and observation: table/KV read, write, observe, and derived-state details.
- Table migrations: migration rules and version evolution examples.
- Primitive API: lower-level primitive contracts and composition details.