Repository navigation
docs(hooks): examples.md Composition must name the three tiers, not two - #995
Merged
NandhaKishorM merged 1 commit intoOct 7, 2026
Conversation
## Composition taught "Installed hooks first, then convenience callables; all share one context", which puts installed at the head and omits the process-wide default tier set via set_default_hooks. compose_hooks returns defaults + installed + normalise_hooks(...), and normalise_hooks puts hooks=[...] entries, then _StartAdapter, then _EndAdapter -- three tiers and two ordering rules, not two. Rewrites the paragraph with the within-scope (hooks=[...] then on_predict_start=/on_predict_end=) and across-scope (defaults then instance then per-call) split, updates the code comments so "installed, runs first" no longer implies a head position, and adds a test_hooks_api.py gate: substring ban on the pre-fix wording, whitespace-flattened token + position checks on the paragraph, and a live-driver assert that compose_hooks emits D, A, B, X, S and puts _StartAdapter before _EndAdapter. Suite 453 -> 466 (+13 checks); mutation harness laya-bench/mutate_examples_compose_order.py catches 6/6 mutants: pre-fix restore, within/across sentence removal, tier swap in prose, compose_hooks installed-before-defaults, and normalise_hooks end-before-start.
aashish254
added a commit
to aashish254/laya
that referenced
this pull request
Oct 6, 2026
The exemption was justified by a claim that does not hold: thirteen open PRs touch tests/test_hooks_api.py, but measured hunk ranges say only one (NandhaKishorM#995, at 954-959) reaches within three lines of the tl_kernels read at 960. The rest sit at 946-952 or 970-975 and merge cleanly, so leaving the read unpinned bought nothing. Pinning it also removes the latent crash: laya/tl_kernels.py decodes as cp1252 today, and one non-cp1252 character added there would take tests (windows) down at the read. The exemption's check is replaced by one with a real failure behind it. This scanner's first version read node.args, which Path.read_text() does not use, so it saw 0 of the evals reads and passed a repo that still had an unpinned docs/evals.md read in tests/test_evals.py. The scan must now reach both shapes, and pinned reads go 27 -> 30.
4 tasks done
Owner
|
Merged in 0.3.29. Same correction as #993 in examples.md: the three composition tiers named as three. Consistency across the hooks pages matters more than it would elsewhere, because a reader checks one page and generalises. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Rewrites the
## Compositionsection ofdocs/hooks/examples.mdand its inlinecode comments, and adds a
tests/test_hooks_api.pygate that holds the page towhat
laya.hooks.compose_hooksandlaya.hooks.normalise_hooksactually do.Why
The page taught:
Two claims in that sentence are wrong against the code:
compose_hooksreturnsdefaults + list(installed) + normalise_hooks(...).The process-wide defaults set via
set_default_hookssit ahead of everyinstance's installed hooks. Naming installed as first contradicts the same
contract docs(hooks): lifecycle.md must place process-wide defaults ahead of installed #991 already fixed on the lifecycle page.
normalise_hooksputshooks=[...]entries first,then the
_StartAdapter(on_predict_start)list, then the_EndAdapter(on_predict_end)list. "Installed hooks first, then convenience callables" flattens that to
two tiers and hides the split between the entries list and the convenience
callables.
The inline comments repeated the same framing:
# installed, runs firstand# convenience, appended.How
New paragraph names both rules:
The three code comments become
hooks=[...] entries run in list order,convenience callables follow the entries,both kinds share one ctx per call.The gate in
tests/test_hooks_api.py:"Installed hooks first, then convenience callables";## Compositionparagraph, whitespace-flattens it, and requiresthe eight tokens (
hooks=[...],on_predict_start=,on_predict_end=,Within one scope,Across scopes,process-wide default,instance's hooks,per-call hooks);Within one scopeprecedesAcross scopes, andthat the tier tokens appear in the order
process-wide default→instance's hooks→per-call hooks;set_default_hooksaDprobe,compose_hookswithinstalled
[A, B],hooks=[X],on_predict_start=S,on_predict_end=E;dispatches every adapter's
on_predict_startforward, asserts the emissionsequence
D, A, B, X, S, then classifies the composed list by which methodeach entry defines and asserts the last two positions are
_StartAdapter(start-only) then
_EndAdapter(end-only).Verification
453 passed, 0 failed.466 passed, 0 failed(+13 checks; token + position + live driver).ruff check laya/ --select=E9,F63,F7,F82,F401,F811 --line-length=120→ All checks passed.python -m compileall -q laya/ tests/→ silent.laya-bench/mutate_examples_compose_order.py→ 6/6 CAUGHT, tree restored:Within one scopetoken;Across scopes+ tier tokens;compose_hooksswaps installed and defaults → live-driver start-order assertion fails;normalise_hooksswaps_StartAdapterand_EndAdapter→ structuralstart_only/end_only kind check fails.
sk-…,ghp_…,gho_…,AKIA…, PEM header,Bearer …,api_key=…): no matches.Deconfliction
gh pr list --repo NandhaKishorM/laya --state open --json filesshows zeroopen PRs touching
docs/hooks/examples.md.tests/test_hooks_api.pyis touched by docs(hooks): patterns.md Composition must name defaults as the head tier #993 (patterns.md) at the tail aftercompile_cpu/kwargs, and by docs(hooks): scope plain callables to on_predict_start=/on_predict_end=, not hooks= #987. This PR's gate is inserted before the# Pin the optional TileLang entry pointscomment (line 957 anchor), whichis above both, so hunks are disjoint from docs(hooks): patterns.md Composition must name defaults as the head tier #993's tail append.
Checklist
CONTRIBUTING.md/AGENTS.md.ruff,compileall, test suites) pass locally.