fix: restore description and content on registered_entity (kernel 0.2.3) #7

Merged

haskos-bot merged 1 commit from feat/registry-columns-0-2-3 into dev

2026-07-27 06:43:13 +00:00

john commented

2026-07-27 06:41:23 +00:00

Owner

What

Bumps the kernel pin to ==0.2.3 and adds migration 0002_registry_columns, which
puts description and content back on registered_entity.

The break

Every POST /documents against haskydocs on the first companyOS instance returned 500:

asyncpg.exceptions.UndefinedColumnError:
column "description" of relation "registered_entity" does not exist

The ADR-009 extraction dropped both columns from the package's RegisteredEntity.
0001_baseline faithfully built the reduced table, so every companyOS database got
a registry that stage apps written against smeos cannot INSERT into. Not a version
skew — both containers ran 0.2.1.

This is the second time description has come up here. The smoke-test docstring
records the first: POST /entities was passing a description kwarg the service does
not accept, "for a column the RegisteredEntity model does not have", and it was fixed
by deleting the caller. That read the reduced model as correct. It was the regression.

Migration

Idempotent by necessity, not by habit. The two entry states diverge here: a fresh
database (homeOS, superclean) needs both columns added; HaskyOS was stamped at
0001_baseline against a database smeos built, which already has them. A plain
ADD COLUMN there fails and wedges the chain, which is the whole point of the stamp
path. ADD COLUMN IF NOT EXISTS makes one migration correct for both.

Both paths run against Postgres 17:

Case	Result
Fresh database, `upgrade head`	0001 → 0002, `alembic check` clean, both columns present
Adopt — columns already there, stamped at 0001	0002 applies without error, `alembic check` clean

Revision ids are capped at 32 characters. The first draft was
0002_registry_description_content (33), and alembic_version_kernel.version_num is
varchar(32). The failure is not a clear one: the DDL succeeds, the final
UPDATE alembic_version_kernel raises StringDataRightTruncationError, and the whole
transaction rolls back — so the tables vanish and it reads like a broken migration.

Tests

tests/test_stage_app_writes.py runs the literal INSERT from
haskydocs-v2/app/services/entity_registration.py. test_api_smoke.py drives this
repo's routes and structurally cannot see the other half of the contract — stage apps
share the database and write kernel tables directly. That blind spot is why this
reached a deployment.

Verified by making it fail:

schema at 0001_baseline only   3 failed
after 0002                     3 passed

Verification

ruff check .   all checks passed
pytest         17 passed

Known asymmetry — follow-up, not fixed here

The columns exist and stage apps can write them, but the kernel's own API cannot:
EntityRegistryService.register takes no description/content, and EntityRegister
does not expose them. That needs a package change to the service signature plus a
schema field, and it is a wider surface than unblocking the regression. Filed as the
next thing rather than folded in here.

## What Bumps the kernel pin to `==0.2.3` and adds migration `0002_registry_columns`, which puts `description` and `content` back on `registered_entity`. ## The break Every `POST /documents` against haskydocs on the first companyOS instance returned 500: ``` asyncpg.exceptions.UndefinedColumnError: column "description" of relation "registered_entity" does not exist ``` The ADR-009 extraction dropped both columns from the package's `RegisteredEntity`. `0001_baseline` faithfully built the reduced table, so **every** companyOS database got a registry that stage apps written against smeos cannot INSERT into. Not a version skew — both containers ran 0.2.1. This is the second time `description` has come up here. The smoke-test docstring records the first: `POST /entities` was passing a `description` kwarg the service does not accept, "for a column the `RegisteredEntity` model does not have", and it was fixed by deleting the caller. That read the reduced model as correct. It was the regression. ## Migration Idempotent by necessity, not by habit. The two entry states diverge here: a fresh database (homeOS, superclean) needs both columns added; HaskyOS was stamped at `0001_baseline` against a database smeos built, which already has them. A plain `ADD COLUMN` there fails and wedges the chain, which is the whole point of the stamp path. `ADD COLUMN IF NOT EXISTS` makes one migration correct for both. Both paths run against Postgres 17: | Case | Result | |---|---| | Fresh database, `upgrade head` | 0001 → 0002, `alembic check` clean, both columns present | | Adopt — columns already there, stamped at 0001 | 0002 applies without error, `alembic check` clean | **Revision ids are capped at 32 characters.** The first draft was `0002_registry_description_content` (33), and `alembic_version_kernel.version_num` is `varchar(32)`. The failure is not a clear one: the DDL succeeds, the final `UPDATE alembic_version_kernel` raises `StringDataRightTruncationError`, and the whole transaction rolls back — so the tables vanish and it reads like a broken migration. ## Tests `tests/test_stage_app_writes.py` runs the literal INSERT from `haskydocs-v2/app/services/entity_registration.py`. `test_api_smoke.py` drives this repo's routes and structurally cannot see the other half of the contract — stage apps share the database and write kernel tables directly. That blind spot is why this reached a deployment. Verified by making it fail: ``` schema at 0001_baseline only 3 failed after 0002 3 passed ``` ## Verification ``` ruff check . all checks passed pytest 17 passed ``` ## Known asymmetry — follow-up, not fixed here The columns exist and stage apps can write them, but the kernel's own API cannot: `EntityRegistryService.register` takes no `description`/`content`, and `EntityRegister` does not expose them. That needs a package change to the service signature plus a schema field, and it is a wider surface than unblocking the regression. Filed as the next thing rather than folded in here.

john added 1 commit

2026-07-27 06:41:23 +00:00

fix: restore description and content on registered_entity (kernel 0.2.3)

CI / Deploy (pull_request) Has been skipped

Details

CI / Docker Build (pull_request) Has been cancelled

Details

CI / Backend (pull_request) Has been cancelled

Details

CI / Detect Changes (pull_request) Has been cancelled

Details

6753920dea

Every POST /documents against haskydocs on a fresh companyOS database returned 500
with UndefinedColumnError. The ADR-009 extraction dropped both columns and
0001_baseline built the reduced table.

Migration is IF NOT EXISTS because HaskyOS was stamped at 0001 against a database
smeos built, which already has the columns. Both entry states tested against PG17.

tests/test_stage_app_writes.py runs haskydocs raw INSERT verbatim — the smoke test
drives routes only and could never have caught this.