workspace-api

name	workspace-api
description	Epicenter workspace API patterns: `defineWorkspace`, `defineTable`, `defineKv`, table `.docs(...)`, migrations, actions, `connect(...)`, `mount(...)`, materializers, and lower-level `createWorkspace` / `openCollaboration` primitives. Use when editing workspace schemas, table/KV access, row child docs, actions, runtime connections, daemon mounts, or collaboration setup.
metadata	{"author":"epicenter","version":"8.0"}

Workspace API

Epicenter workspace definitions, table and KV access, isomorphic action registries, row child docs, runtime connection, daemon mount composition, and lower-level Y.Doc primitives share one model.

Notebook model:

defineWorkspace = pure app contract: id, name, tables, kv, actions, child-doc declarations
connect(...)    = browser/local runtime: storage, optional relay sync, child-doc openers, wipe
mount(...)      = daemon runtime: Yjs log, cloud sync, materializers, daemon actions
createWorkspace = low-level root Y.Doc bundle for internals, tests, and older ports
table.docs(...) = row child-doc declaration; callers open through tables.X.docs.field.open(rowId)

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

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.
• Export an app's shared model as defineWorkspace({ id, name, tables, kv, actions }). The workspace file is the sync contract: schema, branded IDs, KV defaults, isomorphic actions, and table.docs(...) child-doc layouts.
• Put isomorphic actions in the actions: ({ tables, kv, ydoc }) => defineActions({ ... }) callback. Runtime-specific actions live in connect(..., compose) or , where browser, Node, Tauri, extension, materializer, or daemon APIs are in scope.

Reference Map

• Schema definition patterns: defineTable, defineKv, row type inference, KV scalar design, and branded IDs.
• Actions, layout, and attachments: defineWorkspace actions, JSDoc, runtime action composition, file layout, attachment ordering, and script/daemon boundaries.
• 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: direct calls vs adapter invokeAction 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.