patman/KGROO

Fork 0

feat(cam-clear): certify island pass engagement with margin bookkeeping #140

Merged

patman merged 4 commits from patman/island-cert-margin into patman/island-plan-region

2026-08-24 02:25:50 +00:00

AGit

patman commented

2026-08-21 00:58:03 +00:00

Owner

Island lane I-e3, the substantive certification work deferred since I-d: blend-corridor term + inter-sample Lds modulus (station count CHOSEN to keep it under ISLAND_CERT_PEN_FRACr) + adversarial +h refinement. Circular fixture: 16/17 passes certify. Square fixture: 0 certify — honest corner-geometry story documented, back-off floors instead of chasing an unreachable cert. SOUNDNESS GUARD (reviewer HIGH finding, closed): segment_engagement_at is NON-monotone for feature arcs with radius < tool radius (engagement dips; margin becomes anti-conservative) — any reachable sub-radius arc forces certified=false (bound still reported, never certified), pinned by a closed-form dip test + a certifying rho>r control. Uncertified passes stamp certified_error = 2pi (aliasing fix: ZERO meant both "n/a" and "perfectly certified"); the real per-pass certified flag on RingPlan is an API question flagged for Patrick. Reported-not-certified sub-radius bounds are documented as NOT guaranteed upper bounds — cam-drive must not derate on them uncertified. Opus review PASS after conditions.

Island lane I-e3, the substantive certification work deferred since I-d: blend-corridor term + inter-sample L*ds modulus (station count CHOSEN to keep it under ISLAND_CERT_PEN_FRAC*r) + adversarial +h refinement. Circular fixture: 16/17 passes certify. Square fixture: 0 certify — honest corner-geometry story documented, back-off floors instead of chasing an unreachable cert. SOUNDNESS GUARD (reviewer HIGH finding, closed): segment_engagement_at is NON-monotone for feature arcs with radius < tool radius (engagement dips; margin becomes anti-conservative) — any reachable sub-radius arc forces certified=false (bound still reported, never certified), pinned by a closed-form dip test + a certifying rho>r control. Uncertified passes stamp certified_error = 2pi (aliasing fix: ZERO meant both "n/a" and "perfectly certified"); the real per-pass certified flag on RingPlan is an API question flagged for Patrick. Reported-not-certified sub-radius bounds are documented as NOT guaranteed upper bounds — cam-drive must not derate on them uncertified. Opus review PASS after conditions.

patman added 1 commit

2026-08-21 00:58:03 +00:00

feat(cam-clear): certify island pass engagement with margin bookkeeping

CI / build-test (pull_request) Failing after 4s

Details

507a2f5820

Closes the certification gap I-d documented and deferred, and the two
refusal paths I-e2 raised but never asserted
(docs/superpowers/island-clearing-design.md, §4 ID-7/ID-8).

Before this commit `IslandFront::certified` was hardcoded all-false and
`interleave_islands` stamped `Angle::ZERO` into `RingPlan::certified_error`
for every island pass, so downstream could not distinguish a reported
reading from a certified one — and the sampled union bound genuinely was
not certifiable: it had no adversarial perturbation margin, no inter-sample
modulus, and did not even carry the blend corridor.

The margin, three terms folded into one additive penetration widening
(sound because `segment_engagement_at` is monotone non-decreasing in
penetration):

- **Blend corridor**, `2 * blend_corridor`, the same term
  `certified_engagement_core` threads on the outer side and which the
  island path previously ignored outright.
- **Inter-sample modulus**, the term that was missing entirely.
  `distance_to_segment` is 1-Lipschitz in its query point, and
  `sample_points` stations are spaced `perimeter / n` apart, so a feature's
  penetration at an unsampled point exceeds its nearer station's reading by
  at most `perimeter / 2n` — the `L * ds` term with `L = 1`. Rather than
  inherit whatever that is at the caller's display sampling density (where
  it reaches a third of the tool radius and swamps the bound), the
  certificate chooses its own station count so the term lands at or below
  `ISLAND_CERT_PEN_FRAC * tool_radius`, capped at `MAX_ISLAND_CERT_SAMPLES`.
  The applied margin is always recomputed from the stations actually used,
  so hitting the cap weakens certification without ever weakening soundness.
- **Adversarial `+h` perturbation**, mirroring `certified_engagement_core`'s
  refinement loop: the bound is read at the margin and at margin plus `h`,
  and `h` halves while the spread exceeds `CERTIFIED_ERROR_TOL_FRAC` of
  target. Only `+h` is evaluated — monotonicity in penetration makes `-h`
  strictly dominated, unlike the outer path's `pen_of` map. `h` starts at
  the *margin's* own scale over `BLEND_ZONE_INITIAL_DIVISOR`, not the outer
  path's `delta`/`r` scale: measured during this build, a `delta`-scaled
  start does not converge within `MAX_CERTIFIED_REFINEMENTS` halvings at
  all, because of the same `sqrt(pen)` cusp.

Two design decisions worth reviewing:

1. **Stepover selection stays on the raw bound; certification runs once on
   the chosen pass.** Gating the bisection *floor* on the margin-carrying
   bound is actively wrong: `segment_engagement_at` has a `sqrt(pen)` cusp
   at `pen -> 0`, so a floor stepover whose raw engagement is ~0 reads
   `2*sqrt(2*eps/r)` once the margin is added — a few tenths of a radian per
   engaging segment for a small tool, enough to exceed a tight target on its
   own and turn clearable geometry into a spurious `TargetUnachievable`.
   Measured directly: an early build of this commit did exactly that, and
   the `island_family_oracle_direction_holds_for_square_island` proptest
   shrank to `half_width=5mm, r=1mm, target_frac=0.2` to prove it. Trading
   real capability for a certificate is the wrong trade, so the walk chooses
   its stepover exactly as before and the certificate is evaluated once
   afterwards.
2. **A back-off loop reserves headroom for the margin.** The raw bisection
   saturates *exactly* at target, so any positive margin lands the certified
   bound just above it and nothing would ever certify. Each round shrinks
   the stepover by the fraction of target the measured excess represents,
   plus one `CERTIFIED_ERROR_TOL_FRAC` of headroom — without that additive
   term the iteration converges on target from above and never lands
   strictly under it (observed, not theorised). Only one offset is rebuilt
   per round rather than a whole re-bisection, since the shrink is monotone.
   Two floors bound it: `MAX_ISLAND_CERT_BACKOFFS` rounds, and
   `ISLAND_CERT_MIN_STEPOVER_FRAC` of the originally chosen stepover. The
   second matters — a square island's corners sum two segments in the union
   bound and read above target at *every* stepover, so without it the
   back-off drives the step toward zero and the walk exhausts `MAX_PASSES`
   chasing a certificate it can never reach. Past either floor the pass is
   accepted and reported, not refused.

Cost: the certificate is precompute-side (design intent #3) and is bought
with sampling density. `island_union_engagement_pair` evaluates the
unperturbed and perturbed readings in one traversal, sharing the exact
distance query that dominates the cost.

API QUESTION FOR PATRICK (ID-12). `RingPlan` has no per-pass certification
flag, and island passes are genuinely mixed: every island's first orbit is
reported-not-certified (its `max_engagement` is the closed-form
`~pi`-or-above virgin-material bound) while later passes normally certify.
Stamping `Angle::ZERO` for all of them was wrong rather than merely lossy —
zero is this crate's existing "not applicable" reading *and* what a
genuinely certified single-segment pass reports, so a consumer could not
tell a certificate from the absence of one. Within the frozen shape this
commit stamps the real refinement spread for a certified pass and a
saturated `2*pi` for an uncertified one: finite (cam-viz's JSON export stays
well-formed, unlike NaN or infinity), unreachable from any certified path,
and fail-safe under a `certified_error <= tol` gate, which a negative or
zero sentinel would not be. **The real fix is a `certified: Vec<bool>` field
on `RingPlan`**, which is an ID-12 shape change rippling to cam-drive and
cam-viz. Flagged rather than taken unilaterally.

Also in this commit: `residual_freeze_index` is extracted from
`plan_rings_region` (behavior unchanged) purely so both of
`ChannelResidualUnswept`'s raise sites are directly testable. Reaching them
through a whole-pocket fixture appears to be impossible in v1 — the island
family is grown to `max_distance_to_contour(seed, outer) + r`, which always
spans the pocket, so the fronts always meet — and an untestable refusal is
worse than a slightly wider seam.

Tests:
- `channel_residual_unswept_when_fronts_never_meet` and
  `channel_residual_unswept_when_first_loop_already_collides` cover both
  raise sites, the second also confirming the refusal is about collision and
  not loop count.
- `nesting_too_deep_refused_before_planning` pins the depth-2 entry-path
  guarantee end to end: `NestedRegion::classify` refuses first, there is no
  other constructor that could smuggle a depth-2 loop past it, and the
  depth-1 sibling of the same loops does reach the planner.
- `widened_union_bound_dominates_and_reduces_to_the_raw_bound` pins the
  monotonicity the single-additive-margin argument rests on.
- `certified_island_pass_bound_dominates_oracle_between_stations` is the
  substantive one: a certified pass's bound must dominate the exact
  `StockState::engagement` oracle sampled at a deliberately different,
  denser, offset station set than the certificate used — adversarial against
  the inter-sample gap rather than self-confirming. It also pins that a
  circular island does certify passes.
- `interleave_encodes_certification_status_honestly` pins the encoding
  above, driven directly since this module's e2e fixtures legitimately
  refuse before producing a plan.
- `square_island_family_pass_count_and_target_gated` and
  `tiny_island_below_tool_radius_still_builds_family` lose their
  now-obsolete "certified is all-false" assertions. What replaces them is
  deliberately not a certification count: a *square* island certifies
  nothing, for the corner-summation reason above, so that test pins the
  coherence of the outcome instead — the first orbit stays uncertified, the
  corner bound does read above target somewhere, and any pass flagged
  certified genuinely sits at or below target with a converged spread.

Where this leaves certification, measured on the fixtures: a circular
island certifies its non-first passes; a square island certifies none of
them, and that is a property of the union bound at corners rather than of
the margin bookkeeping. The e2e `plan_rings_region` fixtures in this module
all refuse before producing a plan (the pre-existing fully-encircling-ring
entry limitation flagged in the previous commit), so no island pass
certificate reaches a `RingPlan` in-tree yet; `interleave_islands` is
therefore pinned directly.

SOUNDNESS FIX — the additive-margin premise is not universal. The margin
argument above requires engagement to be monotone non-decreasing in
penetration, and the convex arc branch is **not**, once its `rho_e < r`.
With `cos g = (rho_e^2 - a^2 - r^2)/(2ar)` and `a = rho_e - r + delta`,
`dg/da` vanishes at `a = sqrt(r^2 - rho_e^2)`, so across
`a in (r - rho_e, sqrt(r^2 - rho_e^2))` deeper penetration *reduces* the
engagement, bottoming at `2pi - 2*acos(sqrt(r^2 - rho_e^2)/r)`. On that
interval an additive margin *lowers* the bound — anti-conservative, the one
direction a certificate may never move. Inferring monotonicity from the
`0` and `2pi` boundary values, as an earlier comment in this crate did, is
invalid: the boundaries say nothing about the interior.

`plan_rings` is unaffected, because `offset_closed_eroding` clamps envelope
arcs to `min_convex_radius = tool_radius`, so `rho_e >= r` always holds
there. The island walk deliberately uses plain `offset_closed` (ID-8 admits
non-convex envelopes), so sub-`r` envelope arcs are reachable — e.g. from a
filleted concave island notch. `island_certified_engagement` therefore
detects any *reachable* arc of radius below `r`, in the same traversal that
already computes the per-segment distance, and withholds the certificate.
The bound is still computed and reported: it is the certificate, not the
reading, that is unsafe. Both doc claims are corrected — the new one on
`island_union_engagement_widened` and the pre-existing one on
`perturbed_segment_engagement`, whose `+-h` max turns out to be
load-bearing rather than merely defensive.

Pinned by `subradius_arc_engagement_is_non_monotonic` (the dip itself,
against the closed form, with a `rho_e >= r` monotone control) and
`subradius_envelope_arc_is_not_certified` (refusal to certify, with a
`rho_e > r` control that does certify).

Also fixes a latent trap the `2pi` encoding creates for the oracle
assertions: `truth <= reported + certified_error` is *vacuously true* when
`certified_error` is the saturated `2pi`. Today's callers are all
`plan_rings` fixtures that never produce the sentinel, but pointing them at
`plan_rings_region` (I-f) would silently hollow them out. The five
domination assertions now go through `domination_slack`, which contributes
zero slack for an uncertified pass, so such a pass must dominate its raw
reported bound on its own.

Co-authored-by: patman-assist <patrick-ai@kgroo.co>

patman-assist added the

AI Assisted

CAM

Feature

labels

2026-08-21 00:58:23 +00:00

patman added 1 commit

2026-08-21 06:35:48 +00:00

chore: normalize comments

CI / build-test (pull_request) Failing after 5s

Details

8aef273f6a

Co-authored-by: patman-assist <patrick-ai@kgroo.co>

patman added 1 commit

2026-08-23 23:29:29 +00:00

style: rustfmt --edition 2024 drift fix

CI / build-test (pull_request) Waiting to run

Details

338ec7f6f1

Reformats files that predate the runner's current rustfmt; no code changes.

Co-authored-by: patman-assist <patrick-ai@kgroo.co>

patman added 1 commit

2026-08-24 02:03:40 +00:00

merge: sync patman/island-plan-region into island-cert-margin

CI / build-test (pull_request) Successful in 9m7s

Details

8ac9efa631

Certification-status docs kept from this branch; f_loop_clone doc from the base's normalization.

Co-authored-by: patman-assist <patrick-ai@kgroo.co>

patman merged commit 6290378934 into patman/island-plan-region

2026-08-24 02:25:50 +00:00

patman referenced this pull request from a commit

2026-08-24 02:25:51 +00:00

Merge pull request 'feat(cam-clear): certify island pass engagement with margin bookkeeping' (#140) from patman/island-cert-margin into patman/island-plan-region

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

patman/KGROO!140

No description provided.

Rows
Columns