outline_node: the API accepts kinds 'arc' and 'beat' that the database forbids

[letuhao]

What

POST /v1/composition/works/{work_id}/outline/nodes advertises four node kinds:

# services/composition-service/app/db/models.py:39
NodeKind = Literal["arc", "chapter", "scene", "beat"]

The table permits two:

-- loreweave_composition, constraint outline_node_kind_check
CHECK ((kind = ANY (ARRAY['chapter'::text, 'scene'::text])))

So arc and beat pass request validation, reach the INSERT, and die on a Postgres
check constraint. The caller gets a 400 carrying the raw database error:

400 {"detail":{"code":"CONSTRAINT","detail":"new row for relation \"outline_node\"
violates check constraint \"outline_node_kind_check\"\nDETAIL: Failing row contains
(01a09ad8-2de9-..., 01a09a04-ce63-..., ..., beat, r, Beat, null, {}, , null, empty, ...)."}}

Why it matters

A documented, typed part of the API cannot be used. A client written against the schema —
or generated from it — will construct a beat node, receive a 400, and have no way to know
the kind was never storable. Nothing in the contract says two of the four are unusable.

Either the migration is missing (beat/arc were meant to be storable) or the Literal is
stale (they were removed and the type was not). The two halves disagree and only whoever
owns the outline model knows which is correct.

Secondary: the error body is a raw Postgres message

The 400 returns the constraint text and the entire failing row. It is the caller's own
row, so this is not an exposure of anyone else's data, but it does hand out column order
and internal schema, and it is not an error a client can act on. A typed
OUTLINE_NODE_KIND_UNSUPPORTED naming the accepted kinds would be both safer and usable.

How it was found

composition-telemetry.spec.ts B3.3 asserts scene_committed fires on mark-done and NOT
for a non-scene node. To test "not for a non-scene node" it creates a beat — which is why
this surfaced.

Re-measured deliberately: this spec asserts through helpers/db.ts, which until today
defaulted to the BASE stack's Postgres regardless of the browser target, so the original
observation could not be trusted. It reproduces on the isolated stack after that fix.

Not fixed here

Which side moves is a data-model decision, and guessing at it inside a test-repair change
would be the wrong place to make it.

[letuhao]

Investigated — the migration already answered this. The Literal is stale.

I asked which half was wrong: a missed migration, or a stale type. It is the type, and
app/db/arc_lift.py says so in its own header:

M5 — CONTRACT (the point of no return; gated on M4 assertions):
  1. re-assert guards (zero kind='beat', zero orphan arc-children), DELETE the lifted arc
     rows, swap the kind CHECK to ('chapter','scene').

arc was lifted out of outline_node into structure_node (M4), and beat had to be
zero before M5 would run at all. Confirmed on the live stack:

package_migration:  pkg_lift_v1 | 2026-07-11 07:56:35     <- M5 completed
outline_node kinds: chapter x274
                    scene   x489                          <- no arc, no beat anywhere
models.py:39        NodeKind = Literal["arc","chapter","scene","beat"]   <- stale
models.py:283       StructureNodeKind = Literal["saga","arc","part"]     <- where arc lives now

So the CHECK constraint is not a gap — it is the migrated end state, and widening it (the
obvious fix) would re-admit rows a "point of no return" migration deliberately deleted.
arc_lift refuses to run while any kind='beat' exists.

Options

A — Narrow the type to match the schema (recommended).
NodeKind = Literal["chapter", "scene"]. The API stops advertising two kinds that always 400.
Cost: a published type loses two values, so any client still sending them moves from a 400 with
a Postgres message to a 422 with a typed validation error — arguably an improvement, but it is a
contract narrowing and wants a version note.

B — Re-add arc/beat to the CHECK constraint. Not recommended: it reverses M5, re-splits
arcs across two tables, and contradicts a migration explicitly marked irreversible.

C — Leave it. Not recommended: the contract keeps promising something that cannot work, and
the 400 leaks raw schema (the secondary finding in the original report).

The test

composition-telemetry.spec.ts B3.3 creates a beat to check scene_committed is NOT emitted
for a non-scene node. Under option A its claim is unchanged and it should use chapter —
which is a real non-scene node, and the only other kind the model now has. I have not touched
it pending this decision.

Recommendation: A, with the test moved to chapter. Say the word and I will do both, plus
the typed-error improvement for the leaked constraint message.