Llama Stage Patch Changes

llama-stage-patch-changes

Use this skill when changing the Skippy staged-runtime ABI carried in skippy/llama_cpp/patches.

Boundaries

• Keep durable llama.cpp-side changes in the ordered queue under skippy/llama_cpp/patches: top-level core patches first, model_support/series second, and generated/series last.
• Keep the upstream pin in skippy/llama_cpp/upstream.txt.
• Do not edit .deps/llama.cpp as the final artifact; regenerate the patch queue from commits.
• Keep mesh orchestration, protocol compatibility, lifecycle, model management, and API status behavior in Rust.
• Keep one functional boundary per patch. Patch numbers must be unique and contiguous within each queue lane.
• Put family-specific model support in a focused model_support/ patch. Keep reusable staged-runtime machinery in the core lane and generated graph annotations in the generated lane.
• Keep public ABI declarations separate from independently reviewable model lifecycle, loading, and package implementation changes.
• The Skippy native ABI is an internal lockstep boundary, not a stable cross-version compatibility contract. It may change whenever the feature requires it; update the Rust FFI mirror and all callers in the same change.
• Do not preserve old native ABI signatures for compatibility. Bump the ABI version when the boundary changes so mismatches are diagnosable, and make sure the shipped Rust side and native runtime are built from the same queue.
• Do not add a terminal source-reorganization patch. A deliberate layout or ownership change must be represented in the recreated patches that own the affected capabilities.

Native Source Layout

• include/skippy.h is an umbrella only. Put public C ABI declarations in standalone include/skippy/<capability>.h headers.
• Put implementations in src/skippy/<capability>.cpp and private C++ declarations in narrowly named src/skippy/*.h headers.
• Use snake_case capability names. Keep exported symbols prefixed with skippy_ and avoid generic helpers, utils, or expanded common modules.
• src/skippy.cpp is retired. Extend the owning capability module and keep new implementation files below 1,000 lines.
• Make every public header independently compilable as both C11 and C++17. Update explicit CMake source lists and installation rules with new modules.
• Do not preserve retired source include paths unless the task explicitly asks for compatibility. Continue to version and mirror any binary ABI change.

Graph input capabilities

• Derive planned input modes from what the graph can execute, not merely from allocated input tensors. Shared builders may allocate an embedding input that a particular model's metadata forbids using.
• Carry capability declarations through both helper construction and direct input-bundle registration. Keep model restrictions at graph construction; do not add family-name dispatch to the generic planner.
• When adding an input-mode profile, cover both an accepting synthetic model and a rejecting variant. Preserve the graph's existing rejection of invalid direct input while ensuring metadata-only planning never probes that mode.

Native API documentation

• Treat Doxygen-style comments in include/skippy.h and include/skippy/*.h as the source of truth for the public API reference. Every public header and exported skippy_* function must have an adjacent @brief describing what it is used for.

• When the public header surface changes, prepare the patched checkout and regenerate the website reference before finishing the change:

  scripts/prepare-llama.sh pinned
  python3 scripts/generate-skippy-api-doc.py
  python3 scripts/generate-skippy-api-doc.py --check

• Commit mesh/website/src/docs/pages/skippy-api.md alongside the native queue change. The generated page must not be hand-edited, and its inventory must include every public header and exported function in the prepared checkout.

ABI PR documentation requirements

Every pull request that changes the Skippy ABI must include an explicit ABI inventory in the PR description. Do not describe a changed function signature as a newly added function.

The inventory must state, for each change:

• the exact symbol or declaration name and its complete signature or field change;
• whether it was added, changed, deprecated, deleted, or removed;
• the public header containing the declaration;
• the implementation source and Rust FFI mirror, when applicable;
• the ABI version before and after the change;
• why the change is required and what data or behavior it enables;
• that backward compatibility with older native runtimes is intentionally not required, and that the Rust FFI mirror and callers were updated in lockstep;
• the tests that exercise the native ABI boundary, including public-header compilation when a header changes.

Use this compact table in the PR description:

For a changed function signature, call out that it is an ABI change even when the symbol name is unchanged. List removed declarations explicitly as “none” when no functions or fields were deleted; this prevents reviewers from having to infer removals from a patch diff. Keep this inventory synchronized with the ABI version constants in include/skippy/common.h and the mirrors in skippy/crates/skippy-ffi/src/lib.rs. Do not add compatibility shims solely to support an older native runtime; the acceptance criterion is a synchronized Rust/native build and a clear version mismatch if the pieces are mixed.