Close framework gaps: dsp fixture, codegen stress-test, distribution model, NativeAOT docs

[Copilot]

Closes the gaps between "scaffolded" and "safe to depend on by a real consumer app" — specifically the open questions and untested patterns called out in the problem statement.

Codegen parser decision

Resolved open-questions.md item 5: keep the tokenizer. It already satisfies "fail loudly, never silently" — throws CodegenException on any unrecognised construct. libclang would add ~50 MB of native binaries per platform to the dotnet tool NuGet with no correctness gain within the blittable-only constraint.

DSP fixture (native/dsp_fixture/)

Adds the two real-consumer parameter patterns ferrum_add(int,int) never exercised:

// float* buffer + int32_t length
void ferrum_dsp_scale(float* buf, int32_t len, float factor);

// blittable struct out-parameter
void ferrum_dsp_stats(const float* buf, int32_t len, FerrumDspStats* result);

• FerrumDspStats — [StructLayout(Sequential)] with float min_val/max_val/mean + int32_t count
• FerrumDspBindings.cs pre-generated and committed; compiles in the test project via [LibraryImport]
• 15 new xUnit tests (48 total) covering struct fields, pointer params, const stripping, void returns, emitter round-trip, and a regression guard that fails if the committed bindings file drifts from tool output
• Fixed a block-comment bug in the header where float*/int-length text prematurely closed a /** */ comment, causing a parse error

Build pipeline

• native/CMakeLists.txt — added FERRUM_BUILD_DSP_FIXTURE option + add_subdirectory(dsp_fixture)
• native-build.yml — matrix now builds both fixtures across all iOS slices and Android ABIs
• codegen-tests.yml — smoke test runs codegen against both headers; verifies [LibraryImport], struct, and function names in output

Distribution model

Resolved open-questions.md item 1: NuGet + source template. NuGet metadata already existed in both .csproj files. Added templates/Ferrum.Templates.csproj to package maui-ferrum as a dotnet new install Ferrum.Templates package; wired into Ferrum.sln.

NativeAOT real-device verification

Cannot be automated in CI (requires provisioned hardware + Apple Developer credentials). Added explicit manual steps to getting-started.md with a TODO marker — covers both fixtures, expected console checks, and what to record in the PR.

[Copilot]

Pull request overview

This PR closes several “scaffolded vs. production-usable” gaps by adding a second native fixture (DSP-style APIs), expanding codegen validation to cover real consumer ABI patterns, and formalizing a distribution approach that includes both NuGet packages and a dotnet new template.

Changes:

• Add native/dsp_fixture and expand CI native builds (iOS slices + Android ABIs) to build both fixtures.
• Add codegen stress tests for pointer buffer parameters and blittable struct out-parameters, plus a committed generated bindings file with drift-guard tests.
• Add a Ferrum.Templates NuGet project to distribute a MAUI starter template, and update docs to reflect parser/distribution decisions and NativeAOT manual verification steps.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
templates/Ferrum.Templates.csproj	New template-packaging project for dotnet new distribution.
src/Framework.Tests/Codegen/Generated/FerrumDspBindings.cs	Committed generated bindings for the DSP fixture used by drift-guard tests.
src/Framework.Tests/Codegen/DspFixtureCodegenTests.cs	New xUnit suite exercising parser/emitter on DSP fixture header and output stability.
native/dsp_fixture/src/ferrum_dsp.c	Implementation of DSP fixture functions for build/pipeline validation.
native/dsp_fixture/include/ferrum_dsp.h	DSP fixture header designed to exercise pointer + struct-out patterns.
native/dsp_fixture/CMakeLists.txt	CMake target for building/installing the DSP fixture library.
native/CMakeLists.txt	Adds FERRUM_BUILD_DSP_FIXTURE option and includes the new subdirectory.
Ferrum.sln	Adds the templates project and solution folder organization.
docs/open-questions.md	Documents decisions on distribution model and tokenizer vs. libclang.
docs/getting-started.md	Adds manual NativeAOT-on-device verification checklist.
docs/architecture.md	Updates architecture docs to reflect multiple fixtures and tokenizer rationale.
.github/workflows/native-build.yml	Builds and uploads artifacts for both fixtures across iOS and Android matrices.
.github/workflows/codegen-tests.yml	Extends codegen smoke tests to run against both fixture headers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.