Move outstanding work from TODO.md into the issue tracker #17

Merged

andrew merged 2 commits from todo-to-issues into main 2026-08-02 19:47:12 -04:00

Conversation 0 Commits 2 Files Changed 4 +111 -150

tachikoma commented 2026-08-02 19:00:43 -04:00

Collaborator

Copy Link

14 issues, labelled by kind and blast radius, all carrying status::grooming:

Milestone	Issues	What it holds
2.0.x	8	Tests, CI, packaging, defects — no ABI change
2.1.0	3	Additive surface: registry introspection, reservation release, akerr_copy_error
3.0.0	3	The handler-ladder rewrite and the contract changes with it

Three defects were recorded only downstream

Found while moving this file and libakstdlib's at the same time. Each is a defect
in this library, each was written down in a consumer's TODO file, and none had
an entry here:

• #14 — IGNORE() logs a context and never releases it. After
  AKERR_MAX_ARRAY_ERROR ignored failures the pool is exhausted and
  ENSURE_ERROR_READY calls exit(1). libakstdlib's aksl_tree_iterate open-codes
  log-then-release by hand to avoid it; every IGNORE() in libakgl's CLEANUP
  blocks is a leaked slot.
• #15 — the coverage target is not namespaced when embedded, though mutation
  twenty lines below it is. libakstdlib shadows add_custom_target to embed this
  library at all.
• #16 — no akerrorConfigVersion.cmake is installed, so no consumer can ask
  find_dependency(akerror) for a version floor. Sharper now that 1.x and 2.x
  differ on the pool, IGNORE and exit-status mapping.

That is the finding worth more than the three defects. A library whose consumers
record its defects in their own files has no way to see them: each consumer knows
one, nobody sees the pattern, and the workaround gets written once per consumer.

What stays in TODO.md

Why the handler ladder is a major-version change and what it would not fix; why a
copied akerr_ErrorContext is a trap in two specific fields (stacktracebufptr is
self-referential, arrayid is restored after the wipe); why validating more inputs
lowers branch coverage by construction — every PASS site around a call that
cannot fail carries about twenty-five branch outcomes; why the 81.2% mutation score
is a floor rather than a verdict, with the measurement behind it; and why a
registered name is returned by pointer rather than copied.

---

Filed by Tachikoma (Claude Code, Opus 5, 1M context)

**14 issues**, labelled by kind and blast radius, all carrying `status::grooming`: | Milestone | Issues | What it holds | |---|---:|---| | 2.0.x | 8 | Tests, CI, packaging, defects — no ABI change | | 2.1.0 | 3 | Additive surface: registry introspection, reservation release, `akerr_copy_error` | | 3.0.0 | 3 | The handler-ladder rewrite and the contract changes with it | ## Three defects were recorded only downstream Found while moving this file and libakstdlib's at the same time. Each is a defect **in this library**, each was written down in a *consumer's* TODO file, and none had an entry here: - **#14 — `IGNORE()` logs a context and never releases it.** After `AKERR_MAX_ARRAY_ERROR` ignored failures the pool is exhausted and `ENSURE_ERROR_READY` calls `exit(1)`. libakstdlib's `aksl_tree_iterate` open-codes log-then-release by hand to avoid it; every `IGNORE()` in libakgl's `CLEANUP` blocks is a leaked slot. - **#15 — the `coverage` target is not namespaced when embedded**, though `mutation` twenty lines below it is. libakstdlib shadows `add_custom_target` to embed this library at all. - **#16 — no `akerrorConfigVersion.cmake` is installed**, so no consumer can ask `find_dependency(akerror)` for a version floor. Sharper now that 1.x and 2.x differ on the pool, `IGNORE` and exit-status mapping. **That is the finding worth more than the three defects.** A library whose consumers record its defects in their own files has no way to see them: each consumer knows one, nobody sees the pattern, and the workaround gets written once per consumer. ## What stays in TODO.md Why the handler ladder is a major-version change and what it would *not* fix; why a copied `akerr_ErrorContext` is a trap in two specific fields (`stacktracebufptr` is self-referential, `arrayid` is restored after the wipe); **why validating more inputs lowers branch coverage by construction** — every `PASS` site around a call that cannot fail carries about twenty-five branch outcomes; why the 81.2% mutation score is a floor rather than a verdict, with the measurement behind it; and why a registered name is returned by pointer rather than copied. --- Filed by Tachikoma (Claude Code, Opus 5, 1M context)

tachikoma added 1 commit 2026-08-02 19:00:43 -04:00

Move outstanding work from TODO.md into the issue tracker ... a932b976f7

Fourteen issues on source.starfort.tech/andrew/libakerror, labelled by kind and
blast radius and milestoned by what they can land in: 2.0.x for anything that
breaks no ABI, 2.1.0 for additive surface, 3.0.0 for the handler-ladder rewrite.
Everything filed carries status::grooming.

Three of the fourteen were not in this file at all. They are defects in this
library that were written down in a consumer's TODO instead: IGNORE() leaking a
context (#14), the coverage target not being namespaced when embedded (#15),
and no akerrorConfigVersion.cmake being installed (#16). libakstdlib carries a
workaround for each. That is the finding worth keeping -- a library whose
consumers record its defects in their own files cannot see them, and the
workaround gets written once per consumer.

TODO.md keeps the reasoning: why the handler ladder is a major-version change,
why a copied akerr_ErrorContext is a trap in two specific fields, why
validating more inputs lowers branch coverage by construction, why the mutation
score is a floor, and why a registered name is returned by pointer.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tachikoma added 1 commit 2026-08-02 19:24:51 -04:00

Point AGENTS.md at the issue tracker for outstanding work ... 651770f08f

The agent instructions now say where new work goes -- an issue on the forge,
carrying status::grooming until its scope is settled -- and that TODO.md is the
record: why the handler ladder is a major-version change, why a copied
akerr_ErrorContext is a trap, why validating more inputs lowers branch coverage,
and why the mutation score is a floor.

The instruction that matters most here is about consumers. Three defects in this
library -- IGNORE() leaking a context, the un-namespaced coverage target, and the
missing akerrorConfigVersion.cmake -- were written down in libakstdlib's notes
and never here, so each was worked around once per consumer and nobody saw the
pattern. Filing upstream should cost a consumer one issue instead of one
workaround.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

andrew merged commit fa3ed8763c into main 2026-08-02 19:47:12 -04:00

andrew referenced this issue from a commit 2026-08-02 19:47:14 -04:00

Merge pull request 'Move outstanding work from TODO.md into the issue tracker' (#17) from todo-to-issues into main

tachikoma referenced this issue from a commit 2026-08-02 20:49:55 -04:00

Merge pull request 'Move outstanding work from TODO.md into the issue tracker' (#17) from todo-to-issues into main

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

abi-break

Cannot land without a soname bump

api-gap

A caller cannot express something

blast-radius:high

Ordering: highest blast radius

blast-radius:low

Ordering: lowest blast radius

blast-radius:medium

Ordering: middling blast radius

defect

Wrong behaviour reachable from the public API

design-decision

Needs a decision written down before code

docs

Documentation, comments, AGENTS.md

hygiene

Style, dead code, consistency

packaging

Build, install, pkg-config, CMake config

performance

Has a measurement behind it

status::blocked

Waiting on something else -- a decision, a dependency, or another issue

status::grooming

Not yet worked out: scope, approach or priority still being settled

status::ready

Understood well enough to start: scope and approach are settled

test-coverage

A gap in the suites, not a defect

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

tachikoma andrew

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: andrew/libakerror#17