backlog.md

Backlog

Things noticed but deliberately not done. Capture, not a tracker.

Publication note. This file is a historical capture of discoveries made during 1.0.0 development, plus one MANUAL-REACTIVATION-ONLY publishing entry. It is not an active product roadmap.

This exists so that a session can record a real finding without derailing the work item it is in the middle of, and without losing the finding. It is not an issue tracker, it has no workflow, no priorities, and no assignees, and it must not grow into one.

Rules

• One to three lines per entry. If it needs more, it is a work item, not a backlog entry.
• Every entry says what was observed and where, not what should be done about it in detail.
• Entries leave this file in exactly two ways: promoted to a work item in a phase file, or deleted with a one-line reason in the log. Nothing accumulates here indefinitely. Exception: entries under MANUAL-REACTIVATION-ONLY are not eligible for automatic promotion; they wait on an explicit user instruction naming them.
• Reviewed at every phase exit review. Anything still here that nobody has needed in a whole phase is probably a deletion. MANUAL-REACTIVATION-ONLY entries are reviewed for accuracy, not for promotion.
• Architectural questions do not belong here. A question about a boundary, an invariant, or a durable decision goes to docs/decisions/ as a Proposed ADR and blocks the item that raised it.

Entries

Reviewed in full at W-0111; W-0119 added four friction entries from the second uninformed proof and did not re-raise the four consumer-visible items from W-0110 as blockers. W-0120 declared 1.0.0 and left those four friction entries in place. A subsequent owner decision deferred package-index publishing; nothing in this file is eligible for automatic ratchet selection while state.md has no current work item. Nineteen prior entries plus four from W-0119, plus one MANUAL-REACTIVATION-ONLY publishing note.

MANUAL-REACTIVATION-ONLY

Entries in this section are not ordinary backlog. They are not eligible for automatic promotion, selection, or execution by the standard continuation ratchet (docs/development/continuation-prompt.md). A session that finds state.md with no current work item stops; it does not promote these. They become active work only after an explicit future user instruction naming them.

• (MANUAL-REACTIVATION-ONLY) Package-index / public publishing. ADR 0059 established that gated 1.0.0 artifacts are fit to distribute (PyPI channel, TestPyPI-then-PyPI, trusted publishing, no credential in the tree). The owner then decided not to pursue that upload now. Local wheel / git / owner-controlled consumption does not depend on it. Uncommitted Phase 11 / W-0121 planning was removed. Reactivate only on explicit owner instruction to pursue publishing.

Ordinary entries

• (W-0119) The root package publishes no __all__. import entarium; entarium.__all__ is None; every public name lives on a submodule. The README's census example uses a submodule, so it is discoverable, but a consumer who starts at the package root gets silence.
• (W-0119) No example composes a human park across two OS processes. HumanController, deliver, and RequestId are in the API reference; persist_and_resume.py shows cross-process resume for deterministic controllers only. The composition cost design time, not a source read.
• (W-0119) Host writes between PhasedPolicy phases are undocumented. Stopping mid-run via an observer works; nothing says the host may persist environmental items and entity beliefs between a stopped run and a resumed one before a later phase runs.
• (W-0119) Frozen payloads still trip isinstance(..., dict). The API reference already says recorded payloads are frozen mappings; the builder still wrote dict checks first and failed isolation helpers until switching to Mapping. Echo of W-0110 finding 19.
• A consumer suite that wants a mechanical public-import check re-implements the ADR 0045 __all__ scan. The panel (W-0092), scripts/artifact.py (used by consumer_smoke.py), and now tests/test_examples.py (W-0109) each parse __all__ from installed or source modules. Composition did not need a helper; only the assertion did. A published entarium.testing.public_surface() would de-duplicate the suite half and would not widen what a domain can express. Declined as a core change at W-0092; recorded so W-0094 does not rediscover it as "extension machinery."
• Capability grant names are one flat namespace shared by every domain an entity joins. W-0093 put one entity in two domains: its grants are climb.play.north.* and nothing else, and the domains stay apart only because Climb chose a prefixed name. Nothing in the core namespaces a grant by domain, and nothing needs to yet — the panel grants nothing, so no collision is reachable. A third domain that granted a bare play would collide silently, which is the shape to watch rather than a defect today.
• An entity in two domains has one declared controller configuration. §3.2 makes the field a declaration rather than a record of what ran, so the cross-domain chair keeps the panel's review_panel.reviewer while Climb drives it with a capability-requesting controller — which is the architecture working, and W-0093 asserts it. What is unrecorded is that the entity is also drivable as a Climb seat: a host wiring the entity into either domain has to know which mechanism to supply, and durable state names only one. Fine while hosts own wiring; it becomes a question if anything ever tries to resume an entity's participation without being told the domain.
• A host scheduling policy that mutates on next_round fails selection invariance once private scopes exist. Climb (W-0089) stages per-seat private hands before anyone acts; a one-shot policy that flipped a _done flag on the first next_round returned None under derivation's redacted re-ask and raised RoundDerivedFromHiddenContentError even though it read no payload. Counting contributions from the record (as multi-phase policies already do) is pure and passes. W-0090's full-game secrecy suite still schedules cleanly under that pure form.
• A scope label is free text that nothing validates. W-0007 gave Scope a human label, deliberately unread by addressing and visibility, so two scopes may carry the same one and an empty one is legal. Fine while labels are for humans; anything that later displays a scope tree has to decide what an unlabelled or duplicated scope looks like.
• A policy that leaves parked participants out of its rounds cannot deliver to them. InteractionRunner.deliver reconstructs the parked delivery by asking the policy for that entity's turn, so the exclusion ADR 0024 names for keeping an interaction moving around a wait strands the request if the delivering runner is wired with the same policy. Noticed at W-0045; the address stays valid and a runner given a policy that can still offer the turn completes it, so this is a wiring constraint rather than a durable defect. Left here at the W-0072 review rather than promoted, but it becomes easier to hit in P7: a policy that addresses a different participant subset in each phase (W-0076) is exactly the shape that excludes someone who is parked. W-0086 checked what P7 actually did to it: the phase mechanism narrowed it rather than widening it, because RunState.in_phase refuses a phase change while a human wait is outstanding (ADR 0025) and _awaiting_a_person raises before any pass runs, so a multi-phase policy cannot advance past a park. What remains is a policy that omits a parked entity from a subset within its phase — which selection (W-0080, W-0082) makes easy to write — so the entry stays, one shape smaller, and stays a wiring constraint on the delivering runner.
• A derived artifact cannot be forgotten, because nothing addresses one. W-0059 forgets memory entries by (layer, identity) and left derived state alone: artifacts carry no identity, so removing one would have to address it by position or content and would settle the identity question ADR 0026 and ADR 0027 settled deliberately. Whichever item needs it mints derived-artifact identity first, and ADR 0029's record extends additively.
• Elapsed-time aging has nothing to measure against. KeepNewestOnLayer ages by a layer's append order because §7.3 refuses timestamp comparison as an ordering authority across interactions, and a layer accumulates entries from many. A policy that means "older than thirty days" needs the entity-level ingest sequence §7.3 names, which nothing records; noticed at W-0059.
• Three tests pin the presence schema version as a literal. test_belief_confidence.py, test_derived_state.py, and test_memory_identity.py each assert SCHEMA_VERSION == latest_version(PRESENCE) == n, so every bump edits three files that are not about versioning — and test_migration.py already asserts the constant and the registry agree. Fifth time it churned was W-0062.
• A host cannot say "I verified that invocation completed" without discarding execution state. ADR 0034 gives an indeterminate capability invocation two exits — declare the capability repeatable, or discard — and deliberately invented no acknowledgement that closes the participation on evidence from outside Entarium. W-0067 considered it under ADR 0034's "in one item or not at all" and did not adopt it, which replaced the reason rather than closing the entry: a result now has a landing place, so an acknowledgement no longer has to guess what closing records, and what remains is that it writes execution state on evidence from outside Entarium. How much authority a host has over an outstanding entry is an execution-boundary question (W-0068's neighbourhood), not a question about the form of a result (ADR 0035).
• Ten test files now name orchestration/runner.py by path to assert path discipline. rg -l '"runner.py"' tests/ lists ten as of W-0079, which added the assertion that both record_item calls address plan.turn.scope. W-0074 already declined to split the module partly for this reason. The assertions are the right ones and the count is the cost of them; whichever item splits the runner moves all ten deliberately rather than discovering them one failure at a time.
• Grant order is significant in the exposure key, and may be a distinction without a difference. W-0104 made the digest cover each grant whole and deliberately left ordering alone: capability_grants is digested as delivered, so the same two grants in the other order are a different delivery. ADR 0030 says authorization evaluates the set of declarations, which is an argument that order should not key — and changing it is another coverage change and another format version, so it needs a reason better than tidiness.
• The version gate holds existence and path, and nothing holds a signature. ADR 0052's check compares public names, extension points, and durable-format generations against tests/declared_surface.py, so a parameter added without a default, a return type narrowed, or a raise made unconditional passes it while breaking a consumer exactly as a removal would. The ADR states this as a deliberate limit held by review of the census diff; the shape a widening would take is recording each public callable's signature beside its name, which is cheap to derive and expensive to keep honest for protocols and overloads. Start here rather than from scratch if review ever proves insufficient.
• (consumer-visible) Two words are in use for the same idea at different tiers, and which one applies is per-type. ControllerResult and RecordedItem call it payload; Observation and RetainedBelief call it content. Separately, the enum is LifecycleStatus and the field holding it is presence.status. W-0110's builder guessed wrong on all three from the census alone. Renaming any of them costs a version increment under ADR 0052 for a consistency gain, so it needs a better reason than symmetry — but a reference (W-0114) should at least put the pairs where they can be compared.
• (consumer-visible) assemble_context requires capability_grants with no default. W-0110's builder, granting no capability to anybody, wrote capability_grants=presence.capability_grants — a required argument whose only sensible value is read off another required argument, which every consumer that does not use capabilities will write. Defaulting it to the presence's own grants or to () is a small surface change with an ADR 0052 cost; recorded rather than done because "required so the caller states it deliberately" may be the actual intent, and nothing says so.
• (consumer-visible) An offline consumer has no test runner. W-0110 found that pytest is not installable from what the artifact's dependency set provides, so a consumer who installs the way the README documents can only use unittest. W-0113 / ADR 0056 closed the census half: the consumer census is __all__ on the installed package, and the pytest module is not shipped. Whether a test extra should exist at all is the part left here.
• One published constant renders in the reference with no value. DEFAULT_SELECTION_POLICY is an instance of a plain class, so its repr is a memory address; W-0114's renderer refuses an address and falls back to Final[ContextSelectionPolicy] with no = …. Every other constant renders its value. The fix is either a __repr__ on SelectEverything or a renderer that constructs a call form, and neither is worth a change on its own.
• (consumer-visible) The reference does not link a type in a signature to its own entry. docs/reference/public-api.md names AssembledContext in Controller.act as plain text, and the reader scrolls or searches. Every published name has a stable anchor already, so cross-linking is mechanical; left out at W-0114 because it multiplies the diff of every regeneration and nobody has asked for it yet.
• The one-payload-reader assertion is name-based, so a differently-named local escapes it. test_payload_envelope.py::test_exactly_one_module_reads_a_payload_by_key finds subscripting and .get() on names containing payload, fact, or content, which catches the way this would actually regress (a session branching on a field it named honestly) and misses a reader that binds the payload to something else first. Accepted at W-0091 as the cheaper half of a bound that has no exact form — a type-directed check would need the payload's identity tracked through assignment — and recorded because a future widening should start here rather than from scratch.