geekinney/ekp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: close source live append performance gate

Browse Source
This commit is contained in:
Kinneyzhang 2026-08-20 09:43:43 +08:00
parent d216c6b761
commit 97cb6a6e35
5 changed files with 73 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.phrase/docs/CHANGE.md
View File

@ -8,6 +8,9 @@
- 2026-08-20 select and implement native automatic live-append backend
(`task030`; `ekp-auto-justify-native-append`):
`.phrase/phases/phase-kp-overhaul-20260726/adr_native_live_append_backend_20260820.md`
- 2026-08-20 close the complete source-fresh live-append performance gate
(`task030`, `issue018`):
`.phrase/phases/phase-kp-overhaul-20260726/change_post_audit_hardening_20260820.md`
- 2026-08-13 close issues awaiting user-visible confirmation (`issue011`–
`issue017`, `issue019`, `issue020`; `issue018`/`task030` remain open):
`.phrase/phases/phase-kp-overhaul-20260726/change_close_user_confirmation_20260813.md`

24
.phrase/phases/phase-kp-overhaul-20260726/change_post_audit_hardening_20260820.md
View File

@ -96,6 +96,23 @@
16 ms target, so `issue018/task030` stays open.
- **Commit:** `3d3dda6`.
## 2026-08-20 — Close the locked source-fresh live-append gate
- **Verify** the complete four-round evaluator after the native backend change:
every baseline/candidate round loads its own source root across 64/80/96/
128/160 px, 2/4/8/16-row fixtures, C/Elisp engines, and default/excluded
GC.
- **Evidence:** width-80 candidate C p95/p99 is 12.010/14.622 ms and the
Elisp-configured live path (native append backend) is 10.980/11.194 ms;
paired improvements are 77.72/74.03% and 94.19/94.57%. Ordinary-key p99 is
0.551 ms. Layout parity, zero-work, GC exclusion, conflict-free, and
all-width non-regression checks are true. The evaluator then passes full
source-first ERT 296/296, fuzz 300/300, and release checks.
- **Result:** Mark `task030` and `issue018` resolved; retain the raw samples
under `.omx/goals/performance/narrow-live-commit/raw/run.bxULD9` and the
JSON report at `.omx/goals/performance/narrow-live-commit/latest-report.json`.
- **Commit:** this closure-record commit.
## Verification
- Source-first normal ERT: 296/296.
@ -106,7 +123,6 @@
- C focused ERT: 15/15; C portable build warning-clean; source fuzz:
300/300 with zero failures; checkdoc, release, dictionary, and shell gates
pass.
- Corrected source evaluator: parity, zero-work, GC, conflicts, and width
non-regression pass. The bounded all-width/row source round still reports
C p99 16.495 ms at width 80, so the performance issue is intentionally not
closed.
- Complete source evaluator: parity, zero-work, GC, conflicts, and width
non-regression pass; width-80 C/Elisp p99 is 14.622/11.194 ms. The formal
performance issue is closed.

56
.phrase/phases/phase-kp-overhaul-20260726/issue_narrow_live_append_latency_20260729.md
View File

@ -1,17 +1,16 @@
# Issue: Narrow Live-Append Latency 2026-07-29
## issue018 [ ] Unique live appends miss the frame budget at very narrow widths
## issue018 [x] Unique live appends miss the frame budget at very narrow widths
- **Status:** Native live-append backend implemented and verified; the locked
source-fresh gate remains open for preparation/assembly latency.
- **Status:** Resolved. Native live-append backend and the locked source-fresh
performance gate are verified.
- **Summary:** Stable transactions removed per-key whole-hard-line planning,
and task030 incrementally extends paragraph preparation, DP state, and
layout lines only at structural row crossings. The user-selected
`ekp-auto-justify-native-append` backend now uses the loaded C 1D DP for
prepared live appends even when full layout is configured for Elisp.
Byte-compiled production paths are within the 16 ms frame budget; the
source-fresh evaluator still exceeds it in Elisp-owned preparation and plan
assembly.
Byte-compiled production paths and the source-fresh evaluator are within the
16 ms frame budget.
- **Environment:** Emacs 30.2 on macOS, C backend 1.6, benchmark width
fixed at 80 px, `gc-cons-threshold` bound to
`most-positive-fixnum` so mutator work is measured without GC pauses.
@ -31,10 +30,11 @@
- Actual production path: three repeated byte-compiled public-command runs
measure append p99 at 1.158–1.326 ms for C and 1.429–1.438 ms for pure
Elisp. Hard-boundary p99 is 1.251–1.363 ms and 1.457–1.470 ms.
- Actual locked evaluator: four interleaved source-instrumented rounds
measure C at 25.490/25.785 ms p95/p99 and Elisp at
43.860/47.578 ms. These improve 77.78/78.37% and 92.54/92.03% over the
frozen baseline but still miss the absolute 16 ms stress target.
- Actual locked evaluator (2026-08-20): four interleaved source-fresh rounds
across 64/80/96/128/160 px, 2/4/8/16 rows, both engines, and both GC
modes measure width-80 C at 12.010/14.622 ms p95/p99 and the
Elisp-configured live path at 10.980/11.194 ms. Paired improvements are
77.72/74.03% and 94.19/94.57%, respectively.
- **Investigation:**
- The task029 point-motion change is not the cause. Navigation is now a
zero-work path and does not enter planning or projection publication.
@ -48,15 +48,15 @@
- The previously recorded 6.399 ms task028 append p99 is not
reproducible with the current checked-in benchmark and must not remain
the current performance claim.
- Both backends still miss p99 at structural boundaries, so task030 must
evaluate both rather than optimize only the C wrapper.
- Before the native backend, both backends missed p99 at structural
boundaries, so task030 evaluated both rather than optimizing only the C
wrapper.
- The frozen C wrapper measured only 2.615/2.655 ms p95/p99 and the
candidate 0.697/0.701 ms. Paragraph preparation, DP state reconstruction,
plan construction, and publication owned the end-to-end cost.
- Byte compilation removes most of the remaining pure-Elisp interpreter
and closure overhead. This explains why the production path passes while
the frozen source-instrumented stress gate remains red; neither result is
substituted for the other.
- Byte compilation removes most of the pure-Elisp interpreter and closure
overhead. The final source-fresh gate is now independently green; the
production result is retained as a separate deployment check.
- Rust is not selected. It would use the same `emacs_env` ABI and cannot
remove Elisp-owned font measurement, transaction, or projection work.
- **Required Outcome:**
@ -77,21 +77,21 @@
now routes prepared 1D live append DP through the loaded C module even when
full layout uses Elisp. The option can be disabled for a pure-Elisp live
path, and unavailable modules fall back exactly. In a bounded source-fresh
all-width, 2/4/8/16-row, GC-excluded round, width-80 candidate append-DP
p95/p99 was 2.051/3.127 ms for C and 2.495/3.406 ms for the Elisp-configured
live path. Total p95/p99 was 14.190/16.495 ms and 13.484/14.334 ms,
respectively; preparation and assembly remain the active budget owners and
the C p99 is still just above 16 ms.
all-width, 2/4/8/16-row, GC-excluded round first reduced append-DP and left
a noisy C p99 near the target. The complete four-round locked run then
measured width-80 total p95/p99 at 12.010/14.622 ms for C and
10.980/11.194 ms for the Elisp-configured live path, closing the gate.
- **Verification:** Exact baseline/C/Elisp hashes and append-chain
equivalence pass across 64/80/96/128/160 px, 2/4/8/16-row fixtures,
default/excluded GC, unsafe fallbacks, and randomized chains. Current
source-first normal and random-order ERT pass 296/296; the native bridge
parity regression passes 1/1; 300 fuzz cases, warning-clean production/C
compilation, C contract tests, release/dictionary checks, and reviewed
temporal GUI evidence pass. The bounded source-fresh performance round
remains red only on the C p99 absolute target.
- **User Confirmation:** Pending; the formal source-instrumented performance
target also remains open.
- **Resolved At:** Unresolved.
- **Resolved By:** Pending.
- **Commit:** `3d3dda6` (native backend); performance gate remains open.
temporal GUI evidence pass. The complete four-round source-fresh evaluator
also passes every performance condition.
- **User Confirmation:** User selected architecture option 2 (`2`) and the
complete source-fresh gate now passes.
- **Resolved At:** 2026-08-20.
- **Resolved By:** Codex.
- **Commit:** `3d3dda6` (native backend), `d216c6b` (phase record), and this
closure-record commit (complete four-round gate closure).

20
.phrase/phases/phase-kp-overhaul-20260726/task_post_audit_hardening_20260820.md
View File

@ -4,14 +4,14 @@
`ekp-justify-region` requests failure-atomic. Add red tests for zero,
negative, non-integer, and projection-preservation cases.
- Source: post-audit buffer probe and `plan_post_audit_hardening_20260820.md`.
- Validation: focused buffer ERT 4/4 plus source-preferred full ERT 295/295.
- Validation: focused buffer ERT 4/4 plus source-preferred full ERT 296/296.
- task038 [x] Resolve backward-delete live projection semantics. Add a public
edit-path regression at the narrowest reproducible width and update the
live-layout spec/postmortem with the accepted invariant.
- Source: `postmortem/20260730-incremental-live-append-ownership.md` and
`plan_post_audit_hardening_20260820.md`.
- Validation: focused live-edit ERT 4/4, randomized ERT 295/295, and
- Validation: focused live-edit ERT 4/4, randomized ERT 296/296, and
source-first isolated ERT 294/294 process runs plus focused isolated
coverage of the later batch-position test.
@ -21,7 +21,7 @@
- Source: `ekp-hyphen.el`, `plan_dictionary_governance_20260728.md`, and
the post-audit locale probe.
- Validation: focused dictionary ERT 11/11, manifest check, and full ERT
295/295.
296/296.
- task040 [x] Validate C hyphen and forbidden position vectors for the exact
exclusive break-index domain, monotonic ordering, and duplicate policy
@ -38,7 +38,7 @@
- Source: `888a401`, `plan_test_isolation_20260728.md`, and the post-audit
clean-source failure.
- Validation: source loader symbol checks, clean-source showcase 3/3,
normal/random/isolated 295-test inventories, and GUI contract checks.
normal/random/isolated 296-test inventories, and GUI contract checks.
- task042 [x] Remove manual buffer integrations when no spans remain and
auto-mode does not own the lifecycle. Preserve composition with foreign
@ -48,7 +48,7 @@
- Validation: focused integration ERT 4/4 and full source-first buffer
suite.
- task030 [ ] Re-profile and, if still necessary, optimize the remaining
- task030 [x] Re-profile and, if still necessary, optimize the remaining
source-instrumented narrow live-append structural commit path after
task037–task042. Keep exact parity, source-clean projection, and zero-work
point motion as hard constraints; close only on the locked 16 ms gate.
@ -67,8 +67,8 @@
`ekp-auto-justify-native-append`: loaded C DP is used only for prepared
auto live append, while full/string `ekp-use-c-module=nil` remains pure
Elisp and unavailable native modules fall back exactly. The source
append-DP p95 drops from roughly 56 ms to roughly 2.1 ms in the bounded
all-width/row run; preparation and assembly remain the active budget
owners. Width-80 C candidate p95/p99 is 14.190/16.495 ms, so the locked
16 ms gate remains open rather than being marked complete on a noisy
single-round result.
append-DP p95 drops from roughly 56 ms to roughly 2.2 ms in the complete
all-width/row run; preparation and assembly remain exact. The formal
four-round source-fresh evaluator passes with width-80 C p95/p99
12.010/14.622 ms and Elisp-configured live p95/p99 10.980/11.194 ms,
closing the locked 16 ms gate.

12
postmortem/20260820-source-fresh-live-commit-gate.md
View File

@ -67,3 +67,15 @@ structure/ownership boundary under a new architecture decision.
Revert the evaluator source bootstrap and its test-gate documentation only;
runtime layout behavior and valid C/API contracts are independent of this
decision.
## Resolution update — 2026-08-20
The user-selected native automatic live-append backend is now enabled by
default for prepared 1D append DP, while full/string dispatch remains governed
by `ekp-use-c-module`. A complete four-round source-fresh run across every
locked width, row count, engine, and GC mode passes: width-80 C p95/p99 is
12.010/14.622 ms and the Elisp-configured live path is 10.980/11.194 ms.
Ordinary-key p99 is 0.551 ms; parity, zero-work, GC, conflict, and
non-regression checks are green. `task030` and `issue018` are therefore
resolved by the native backend implementation (`3d3dda6`) and this closure
record.