feat: expose description and content on the entity API (kernel 0.2.4) #8

Merged

haskos-bot merged 1 commit from feat/entity-description-api into dev

2026-07-27 07:12:54 +00:00

john commented

2026-07-27 07:10:08 +00:00

Owner

What

Bumps the pin to ==0.2.4 and exposes description and content on the entity API.

0.2.3 restored the columns. 0.2.4 gave EntityRegistryService.register parameters for
them. This is the last hop: POST /entities can now send them and GET /entities
returns them. Until now only raw SQL could reach the fields, so haskydocs could write a
description this API could neither set nor show.

Optional on the way in, always present on the way out

EntityRegister.description and .content are str | None = None.
EntityResponse declares them str, because the columns are NOT NULL.

register is an upsert and haskydocs writes description by raw SQL on
entity_type='document' rows. If omitting the field meant "", every rename through
this endpoint would blank what the stage app stored. None means "no opinion".

The earlier fix went the wrong way

This file's own docstring records it: POST /entities used to pass a description
kwarg, that was found to be a 500, and it was fixed by deleting the kwarg — reading the
reduced model as correct. smeos has the column and haskydocs writes it, so the model
was the regression. The docstring is corrected here rather than left to mislead the
next reader.

Tests

Three added to test_api_smoke.py, against a real database:

both fields round-trip through POST and back out of the response
omitting them on a second write does not blank the stored value — the upsert case
omitting them on a first write stores "", not null

Verification

ruff check .   all checks passed
ruff format    30 files already formatted
pytest         20 passed

## What Bumps the pin to `==0.2.4` and exposes `description` and `content` on the entity API. 0.2.3 restored the columns. 0.2.4 gave `EntityRegistryService.register` parameters for them. This is the last hop: `POST /entities` can now send them and `GET /entities` returns them. Until now only raw SQL could reach the fields, so haskydocs could write a description this API could neither set nor show. ## Optional on the way in, always present on the way out `EntityRegister.description` and `.content` are `str | None = None`. `EntityResponse` declares them `str`, because the columns are NOT NULL. `register` is an upsert and haskydocs writes `description` by raw SQL on `entity_type='document'` rows. If omitting the field meant `""`, every rename through this endpoint would blank what the stage app stored. `None` means "no opinion". ## The earlier fix went the wrong way This file's own docstring records it: `POST /entities` used to pass a `description` kwarg, that was found to be a 500, and it was fixed by deleting the kwarg — reading the reduced model as correct. smeos has the column and haskydocs writes it, so the model was the regression. The docstring is corrected here rather than left to mislead the next reader. ## Tests Three added to `test_api_smoke.py`, against a real database: - both fields round-trip through `POST` and back out of the response - **omitting them on a second write does not blank the stored value** — the upsert case - omitting them on a first write stores `""`, not `null` ## Verification ``` ruff check . all checks passed ruff format 30 files already formatted pytest 20 passed ```

john added 1 commit

2026-07-27 07:10:08 +00:00

feat: expose description and content on the entity API (kernel 0.2.4)

CI / Deploy (pull_request) Has been skipped

Details

CI / Backend (pull_request) Has been cancelled

Details

CI / Detect Changes (pull_request) Has been cancelled

Details

CI / Docker Build (pull_request) Has been cancelled

Details

534126f1ff

0.2.3 restored the columns, 0.2.4 gave register() parameters, this is the last hop.
Until now only raw SQL could reach them, so haskydocs could write a description the
kernel API could neither set nor show.

Optional in, always present out: register is an upsert and omitting the field must
not blank what a stage app stored.