Pre-push review: url-locator-generalisation

What Changed

Asterism identifies which story a captured page belongs to using taught URL rules. A rule used to have to name both neighbours of the URL piece it wanted — and on most sites the right-hand neighbour is the story's own name, so every rule only matched the story it was taught from. Now a rule side can be left open ("the component after fiction, whatever follows it"), and teaching produces that by default. Separately, a rule whose stored bytes can't be read used to be silently replaced with a made-up rule that matched nothing — erasing story identities and even reaching backup files. It now fails honestly: capture keeps working, the health check names the rule, re-teaching repairs it, and a backup either omits it or refuses to write a file.

Why It Matters

The reader repairs their pinned sites by re-teaching — no migration — and the repair provably changes no story identity. A silent-corruption path into backups is closed.

Key Concepts

Anchor: one side of the bracket a rule uses to find a path component — start, end, a literal neighbour, or now unanchored. Identity key: the string grouping captures into one story; repairs must not change any. Teaching: tapping components of a real URL to show the app a site's structure.

Changes Overview

Three phases, ordered by Decision 5 — the integrity fix lands before the feature that makes undecodable bytes ordinary. Phase 1 replaces the fabricating accessor with a throwing getter plus failable setDefinition, adds ComposedURLRuleState (none/readable/unreadable, carrying id+version because the version projection must offer version + 1, never a colliding 1), gives the validator a typed unreadableURLRule case, and bounds export by archive reachability (Q14): omit an unreadable row nothing cites, refuse — writing no file — over one that records cite. Phase 2 adds PathAnchor.unanchored (synthesized Codable, existing bytes pinned, the positional _0 key tripwired per Q11), a validation guard against both-sides-unanchored, the unanchored-right teaching default, and moves the editor's gestures into URLEditorState so Req 3.7's template retention is real and testable. Phase 3 proves the repairs through that gesture path.

Implementation Approach

• State over sentinel wherever a third state exists; the enum carries what its consumers need.
• Per-consumer try? decisions per the design's consumer table rather than a blanket throw — a propagated throw would fail capture and close the repair route.
• Testability by extraction: the gestures were private View members; the regression must drive them or it passes while the defect ships.

Trade-offs

Wholesale archive refusal on older builds instead of a format bump (Decision 2); m.fanfiction.net re-taught work-only, losing an inexpressible sequence locator (Q8); merge dead-ends at commit on an affected hostname until re-teaching (Q15); no anchoring control ships until a site needs one.

Technical Deep Dive

• Wire tripwire: PathAnchor.literal's payload key is the positional _0; labelling it orphans every archive. Pinned by test (Q11). unanchored encodes as {"unanchored":{}}; older builds refuse such archives wholesale before the checksum (Decision 2, Req 4.8).
• Validation vs selection: both-unanchored resolves on a single-component path, so the refusal is a validate guard — enforced at construction and at import via the codec's reference validation; the import half gained its test in review.
• Export edge: the reachability partition counts an id unreadable only when no row decodes; a duplicate-UUID group with one corrupt row can still reach the mapper (representative chosen by ordering, not decodability) — now a named unrepresentableValue refusal, failing closed.
• Merge invariant: WorkMergeBasis refuses the contradictory currentRule-plus-ruleUnreadable state in its throwing init; the = false default otherwise let a forgetful builder re-open the identity-clearing fold Q15 prevents.
• Preview derivations cached per outcome via didSet (ordering safe: frozenBasis always assigned first); previousIdentityKey is String?, killing an empty-string sentinel that collided with real version-1 keys.
• Fixture truth (Q20): seeding capture→teach→capture, through projectCapture/commitCapture — capture(_:) applies no rules, and teaching a fully-seeded site manufactures a phantom Work collision.

Architecture Impact

ComposedTeachingBasis gained a source-compatible third state behind a computed currentURLRule. The editor View is render-and-dispatch only; the state machine is shared ground with optional-chapter-sequence (Q12). Every repaired site forfeits Work-URL candidates (WorkURLPlanner requires right == .end) — the builder's .end-when-last preference is the sole remaining route.

Potential Issues

The archive regression pins a reconstructed corpus (Q16) — replace it if the real export ever enters the repo. The title-rule export side keeps refuse-always (Q21), a fail-closed dead end if an undecodable historical title row ever appears. Per-Entry rule decodes in the validator replay remain (microseconds; memoization skipped as not worth threading a cache through two private signatures).