@@ -373,7 +373,7 @@ The **HttpDispatcher** is the central request router in ObjectStack.
373373
374374### Dispatcher Error Codes
375375
376- | HTTP Status | Error Type | When |
376+ | HTTP Status | Error Code | When |
377377| :------------| :-----------| :-----|
378378| 404 | ` ROUTE_NOT_FOUND ` | No route matches the path |
379379| 405 | ` METHOD_NOT_ALLOWED ` | Route exists but method not supported |
@@ -390,9 +390,9 @@ Every endpoint has a handler status:
390390| ` stub ` | Handler exists but returns mock data |
391391| ` planned ` | Handler is defined in the spec but not yet coded |
392392
393- > ** Best practice:** Always set ` handlerStatus ` explicitly. The dispatcher
394- > returns ` 501 NOT_IMPLEMENTED ` for ` stub ` and ` planned ` handlers, giving
395- > clear feedback to API consumers .
393+ > ** Best practice:** ` handlerStatus ` is DOCUMENTATION — nothing reads it at
394+ > runtime. The dispatcher's ` 501 NOT_IMPLEMENTED ` comes from the endpoint
395+ > executor, never from this field .
396396
397397---
398398
@@ -406,9 +406,9 @@ Realtime contracts are pointer-style — read the spec source for exact shapes:
406406 ` RealtimeConfigSchema ` . Note: the ` RealtimeEventType ` enum is declared but
407407 not yet enforced — the runtime emits ` data.record.* ` event names instead.
408408- ` node_modules/@objectstack/spec/src/api/websocket.zod.ts ` — the WebSocket
409- message protocol: subscribe/unsubscribe messages, event delivery with
410- filters, presence, cursor and collaborative-edit messages, and
411- ack/error/ping/pong frames.
409+ message protocol: subscribe/unsubscribe messages, event delivery
410+ ( ` filters ` not enforced) , presence, cursor and collaborative-edit
411+ messages, and ack/error/ping/pong frames.
412412
413413---
414414
@@ -502,13 +502,12 @@ Registered driver ids in the datasource driver catalog:
502502| :-------| :---------|
503503| ` postgres ` | Primary production database |
504504| ` mysql ` | Legacy systems, WordPress integration |
505- | ` mongo ` | Document store (MongoDB ) |
505+ | ` mongodb ` | Document store (` mongo ` is a legacy alias ) |
506506| ` sqlite ` | Local development, embedded apps |
507+ | ` sqlite-wasm ` | Browser / edge SQLite (WASM) |
508+ | ` turso ` | Edge SQLite (` @objectstack/driver-turso ` ) |
507509| ` memory ` | Unit tests, development |
508510
509- Edge SQLite (Turso/libSQL) is available via the separate
510- ` @objectstack/driver-turso ` package (driver name ` turso ` ).
511-
512511---
513512
514513## Inter-Service Communication
@@ -518,7 +517,7 @@ Edge SQLite (Turso/libSQL) is available via the separate
518517ObjectStack uses typed service contracts defined in ` @objectstack/spec/contracts ` .
519518The data contract is ` IDataEngine ` (` find(objectName, query?: EngineQueryOptions) ` ,
520519` findOne ` , ` insert ` , ` update ` , ` delete ` , ` count ` , ` aggregate ` , plus optional
521- ` vectorFind ` /` batch ` / ` execute ` ) — there is no ` DataService ` contract.
520+ ` vectorFind ` /` execute ` ) — there is no ` DataService ` contract, and no ` batch ` .
522521
523522### Kernel Service Resolution
524523
@@ -548,19 +547,18 @@ async function firstTenAccounts() {
548547 for business logic that cannot be expressed through CRUD + triggers.
5495483 . ** Return consistent error shapes.** The dispatcher envelope is
550549 ` DispatcherErrorResponseSchema ` : `{ success: false, error: { code, message,
551- type ?, route?, service?, hint? } }` , where ` code` is the ** numeric ** HTTP
552- status and ` code ` /` message ` are required. General API errors use
550+ httpStatus ?, route?, service?, hint? } }` , where ` code` is the ** semantic **
551+ string and ` code ` /` message ` are required. General API errors use
553552 ` ErrorResponseSchema ` (` errors.zod.ts ` ). Be aware the shipped data routes
554553 return flat ` { error, code } ` bodies instead (e.g. ` CONCURRENT_UPDATE ` →
555554 409, ` VALIDATION_FAILED ` → 400) — do not assume every error arrives in the
556555 ` success: false ` envelope.
5575564 . ** Document every endpoint** with ` description ` and response schemas.
558- 5 . ** Set ` handlerStatus ` ** to communicate implementation progress to consumers.
559- 6 . ** Apply least-privilege auth.** Every endpoint should declare its required
557+ 5 . ** Apply least-privilege auth.** Every endpoint should declare its required
560558 permissions explicitly.
561- 7 . ** Design idempotent writes deliberately.** ` upsert ` exists as an
562- ` apiMethods ` enum value, but ` @objectstack/rest ` generates no upsert route
563- today. External integrations should query by a unique external ID and then
559+ 6 . ** Design idempotent writes deliberately.** ` upsert ` is DERIVED ( ` create ` ∧
560+ ` update ` ), not an ` apiMethods ` value, and ` @objectstack/rest ` generates no
561+ upsert route today. External integrations query by a unique external ID and
564562 branch to create or update (the per-object
565563 ` POST /api/v1/data/{object}/batch ` endpoint can group those writes).
566564
0 commit comments