Skip to content

Commit 5a5804a

Browse files
committed
docs(skills): correct nine false behavioral claims in objectstack-api
Flight ⑦ of the published-skills factual sweep (program #13658). Every claim verified against the implementing code plus executed probes; corrections are byte-neutral-or-shrinking under the token ratchet (net -8 tokens / -2 lines). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EnE7G31tqbxN1rqpQmzurT
1 parent 6b285ec commit 5a5804a

1 file changed

Lines changed: 17 additions & 19 deletions

File tree

‎skills/objectstack-api/SKILL.md‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -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
518517
ObjectStack uses typed service contracts defined in `@objectstack/spec/contracts`.
519518
The 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.
549548
3. **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.
557556
4. **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

Comments
 (0)