Migrate 2.0.0 errors to daw_error/v1 #43

New issue

Open

opened 2026-08-10 08:35:33 +02:00 by michael · 0 comments

michael commented

2026-08-10 08:35:33 +02:00

Owner

Goal

Migrate daw-lua-common 2.0.0 from string errors to the structured daw_error/v1 return contract before public release.

Session rationale

The session explicitly decided to break the still-private 2.0.0 once more now, because only daw-lua-common and daw-lua-net have already been moved to 2.0.0. Doing the structured-error migration now avoids repeating the same breaking migration across roughly forty later modules.

Scope

Replace public error strings with valid immutable daw_error/v1 objects.
Keep the public return convention result, nil or nil, err; predicate functions retain their legitimate false, nil result where applicable.
Populate the required contract fields decided for daw_error/v1, including stable machine-readable code, source, technical message, and unique error identity.
Preserve nested causes as full daw_error/v1 objects.
Do not mutate existing error objects to append later failures; use the separate error-report contract where follow-up failures need to be grouped.
Update validation/helpers and tests needed by the Lua binding so returned errors conform to daw_error/v1.
Remove assumptions that callers parse [ERROR] ... prefixes from returned errors; textual rendering belongs to the formatter/UI layer.

Acceptance criteria

Every public failure path returns nil, <valid daw_error/v1 object> rather than a formatted error string.
Success and predicate return arity remains compatible with the DAW 2.x return rules.
Nested cause values are complete valid daw_error/v1 objects and cannot form cycles.
Returned error objects contain no non-serializable Lua runtime values.
Existing tests are updated for object-based errors and new contract-validation cases are added where needed.
make test passes on the Lua versions currently supported by the repository.

Cross-repository context

The normative contract is maintained in DAW/daw-contracts. daw-lua-net must be migrated to the same error contract so both 2.0.0 common libraries expose a consistent API.

## Goal Migrate `daw-lua-common` 2.0.0 from string errors to the structured `daw_error/v1` return contract before public release. ## Session rationale The session explicitly decided to break the still-private 2.0.0 once more now, because only `daw-lua-common` and `daw-lua-net` have already been moved to 2.0.0. Doing the structured-error migration now avoids repeating the same breaking migration across roughly forty later modules. ## Scope - Replace public error strings with valid immutable `daw_error/v1` objects. - Keep the public return convention `result, nil` or `nil, err`; predicate functions retain their legitimate `false, nil` result where applicable. - Populate the required contract fields decided for `daw_error/v1`, including stable machine-readable `code`, `source`, technical `message`, and unique error identity. - Preserve nested causes as full `daw_error/v1` objects. - Do not mutate existing error objects to append later failures; use the separate error-report contract where follow-up failures need to be grouped. - Update validation/helpers and tests needed by the Lua binding so returned errors conform to `daw_error/v1`. - Remove assumptions that callers parse `[ERROR] ...` prefixes from returned errors; textual rendering belongs to the formatter/UI layer. ## Acceptance criteria - [ ] Every public failure path returns `nil, <valid daw_error/v1 object>` rather than a formatted error string. - [ ] Success and predicate return arity remains compatible with the DAW 2.x return rules. - [ ] Nested `cause` values are complete valid `daw_error/v1` objects and cannot form cycles. - [ ] Returned error objects contain no non-serializable Lua runtime values. - [ ] Existing tests are updated for object-based errors and new contract-validation cases are added where needed. - [ ] `make test` passes on the Lua versions currently supported by the repository. ## Cross-repository context The normative contract is maintained in `DAW/daw-contracts`. `daw-lua-net` must be migrated to the same error contract so both 2.0.0 common libraries expose a consistent API.

michael added the

coordination/cross-repo

labels