Skip to content

docs(hooks): examples.md Composition must name the three tiers, not two - #995

Merged
NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-hooks-examples-compose-order
Oct 7, 2026
Merged

NandhaKishorM merged 1 commit into
NandhaKishorM:mainfrom
aashish254:fix-hooks-examples-compose-order

Conversation

@aashish254

Copy link
Copy Markdown
Contributor

What

Rewrites the ## Composition section of docs/hooks/examples.md and its inline
code comments, and adds a tests/test_hooks_api.py gate that holds the page to
what laya.hooks.compose_hooks and laya.hooks.normalise_hooks actually do.

Why

The page taught:

Installed hooks first, then convenience callables; all share one context.

Two claims in that sentence are wrong against the code:

  • Head tier. compose_hooks returns defaults + list(installed) + normalise_hooks(...).
    The process-wide defaults set via set_default_hooks sit ahead of every
    instance'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.
  • Within-scope order. normalise_hooks puts hooks=[...] 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 first and # convenience, appended.

How

New paragraph names both rules:

Within one scope, hooks=[...] entries run in list order and the
on_predict_start= / on_predict_end= convenience callables follow. Across
scopes, process-wide default hooks come before an instance's hooks, and an
instance's hooks before per-call hooks. Every hook of one call shares that
call's context.

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:

  1. bans the pre-fix substring "Installed hooks first, then convenience callables";
  2. splits the ## Composition paragraph, whitespace-flattens it, and requires
    the eight tokens (hooks=[...], on_predict_start=, on_predict_end=,
    Within one scope, Across scopes, process-wide default, instance's hooks, per-call hooks);
  3. asserts the position of Within one scope precedes Across scopes, and
    that the tier tokens appear in the order process-wide default →
    instance's hooks → per-call hooks;
  4. runs a live driver: set_default_hooks a D probe, compose_hooks with
    installed [A, B], hooks=[X], on_predict_start=S, on_predict_end=E;
    dispatches every adapter's on_predict_start forward, asserts the emission
    sequence D, A, B, X, S, then classifies the composed list by which method
    each entry defines and asserts the last two positions are _StartAdapter
    (start-only) then _EndAdapter (end-only).

Verification

  • Baseline suite: 453 passed, 0 failed.
  • Extended suite: 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.
  • Mutation harness laya-bench/mutate_examples_compose_order.py → 6/6 CAUGHT, tree restored:
    • m1 pre-fix wording restored → gate fails on both substring ban and token check;
    • m2 within-scope sentence dropped → gate fails on Within one scope token;
    • m3 across-scope sentence dropped → gate fails on Across scopes + tier tokens;
    • m4 tier swap in prose (per-call before instance) → position check fails;
    • m5 compose_hooks swaps installed and defaults → live-driver start-order assertion fails;
    • m6 normalise_hooks swaps _StartAdapter and _EndAdapter → structural
      start_only/end_only kind check fails.
  • Secret scan on the full diff (sk-…, ghp_…, gho_…, AKIA…, PEM header,
    Bearer …, api_key=…): no matches.

Deconfliction

Checklist

  • My PR focuses on one specific issue or feature.
  • I have read and followed CONTRIBUTING.md / AGENTS.md.
  • I have added or updated tests that verify the fix.
  • All CI gates (ruff, compileall, test suites) pass locally.

## 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.
@NandhaKishorM
NandhaKishorM merged commit 177c17a into NandhaKishorM:main Oct 7, 2026
32 checks passed
@NandhaKishorM

Copy link
Copy Markdown
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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants