first release

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+
+[*.{json,yaml,yml}]
+indent_size = 2
+
+[*.cs]
+csharp_style_namespace_declarations = file_scoped:suggestion
+
+[*.md]
+trim_trailing_whitespace = false

.github/FUNDING.yml

@@ -1,4 +1,2 @@
-# These are supported funding model platforms
-
 github: [magiccodingman]
 custom: ['https://sayou.biz/support', 'https://paypal.me/lancewr']

.github/actionlint.yaml

@@ -0,0 +1,3 @@
+self-hosted-runner:
+  labels:
+    - magicquant-smoke

.github/pull_request_template.md

@@ -0,0 +1,7 @@
+## Change
+
+Describe the problem and resulting behavior. Note changes to numerical policy, configuration, paths, or persisted formats.
+
+## Validation
+
+List relevant tests and any model/hardware checks. State material limitations.

.github/workflows/dotnet.yml

@@ -0,0 +1,47 @@
+name: .NET checks
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        configuration: [Debug, Release]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m unittest discover -s scripts -p "test_*.py"
+      - run: dotnet restore MagicQuant.sln --locked-mode -warnaserror
+      - run: dotnet build MagicQuant.sln --configuration ${{ matrix.configuration }} --no-restore -warnaserror
+      - run: dotnet test MagicQuant.sln --configuration ${{ matrix.configuration }} --no-build --blame-hang-timeout 2m --blame-hang-dump-type none --logger trx --logger "console;verbosity=normal" --results-directory TestResults
+      - run: dotnet pack src/MagicQuant --configuration ${{ matrix.configuration }} --no-restore -p:Version=0.0.0-ci -o artifacts -warnaserror
+      - run: python scripts/package_smoke.py artifacts/MagicQuant.0.0.0-ci.nupkg
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results-${{ matrix.os }}-${{ matrix.configuration }}
+          path: TestResults/
+  secrets:
+    name: Secret scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python scripts/scan_secrets.py

.github/workflows/model-smoke.yml

@@ -0,0 +1,41 @@
+name: Model smoke (manual)
+on:
+  workflow_dispatch:
+    inputs:
+      model_path:
+        description: Complete source model on the trusted runner
+        required: true
+      llama_root:
+        description: Existing llama.cpp checkout on the trusted runner
+        required: true
+      runtime_root:
+        description: Existing MagicQuant runtime with Python dependencies
+        required: true
+      output_root:
+        description: Dedicated smoke output directory on the trusted runner
+        required: true
+permissions:
+  contents: read
+jobs:
+  smoke:
+    # Never trigger self-hosted execution automatically from untrusted pull requests.
+    runs-on: [self-hosted, magicquant-smoke]
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - run: dotnet restore MagicQuant.sln --locked-mode
+      - run: dotnet test tests/MagicQuant.Tests -c Release --no-restore --filter Category=ModelSmoke --logger trx --results-directory TestResults
+        env:
+          MQ_RUN_MODEL_SMOKE: '1'
+          MQ_SMOKE_MODEL: ${{ inputs.model_path }}
+          MQ_SMOKE_LLAMA_ROOT: ${{ inputs.llama_root }}
+          MQ_SMOKE_RUNTIME_ROOT: ${{ inputs.runtime_root }}
+          MQ_SMOKE_OUTPUT: ${{ inputs.output_root }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: smoke-test-results
+          path: TestResults/*.trx

.github/workflows/publish-nuget.yml

@@ -0,0 +1,84 @@
+name: Publish NuGet
+on:
+  push:
+    branches: [release]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  validate:
+    if: github.ref == 'refs/heads/release'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: dotnet restore MagicQuant.sln --locked-mode -warnaserror
+      - run: dotnet build MagicQuant.sln -c Release --no-restore -warnaserror
+      - run: dotnet test MagicQuant.sln -c Release --no-build --blame-hang-timeout 2m --blame-hang-dump-type none
+      - run: python -m unittest discover -s scripts -p "test_*.py"
+      - run: dotnet pack src/MagicQuant -c Release --no-restore -p:Version=0.0.0-ci -o artifacts -warnaserror
+      - run: python scripts/package_smoke.py artifacts/MagicQuant.0.0.0-ci.nupkg
+  publish:
+    needs: validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment: release
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Reserve or reuse the version for this commit
+        id: version
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          python scripts/release_version.py --reserve
+      - run: dotnet restore MagicQuant.sln --locked-mode -warnaserror
+      - name: Pack exact release version
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        run: dotnet pack src/MagicQuant -c Release --no-restore -p:Version="$RELEASE_VERSION" -p:ContinuousIntegrationBuild=true -o artifacts -warnaserror
+      - name: Validate the release package
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        run: python scripts/package_smoke.py "artifacts/MagicQuant.$RELEASE_VERSION.nupkg"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: nuget-${{ steps.version.outputs.version }}
+          path: artifacts/*.nupkg
+      - name: NuGet login through trusted publishing
+        uses: NuGet/login@v1
+        id: login
+        with:
+          user: ${{ secrets.NUGET_USER }}
+      - name: Publish tested package
+        env:
+          NUGET_API_KEY: ${{ steps.login.outputs.NUGET_API_KEY }}
+        run: dotnet nuget push artifacts/*.nupkg --source https://api.nuget.org/v3/index.json --api-key "$NUGET_API_KEY" --skip-duplicate
+      - name: Create release record
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if ! gh release view "v$RELEASE_VERSION" >/dev/null 2>&1; then
+            gh release create "v$RELEASE_VERSION" --verify-tag --title "MagicQuant $RELEASE_VERSION" --generate-notes
+          fi

.gitignore

@@ -1 +1,81 @@
 .obsidian/
+
+# Build results
+bin/
+obj/
+
+# Rider / JetBrains
+.idea/
+*.sln.iml
+
+# Visual Studio user settings
+*.user
+*.userosscache
+*.suo
+*.cache
+*.dbmdl
+*.bak
+*.ncb
+*.opendb
+*.VC.db
+
+# Other common C# stuff
+*.log
+*.vs/
+
+# Local campaigns and generated model/runtime artifacts
+config.local.yaml
+*.local.yaml
+*.dev.yaml
+**/MagicQuant_SQLite.db*
+*.duckdb
+*.duckdb.wal
+*.gguf
+*.safetensors
+.MagicQuant_tmp/
+TestResults/
+artifacts/
+
+__pycache__/
+
+# Visual Studio / Rider / VS Code per-user and machine state
+.vs/
+.idea/
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.example.json
+*.DotSettings.user
+*.sln.DotSettings.user
+*.slnx.user
+*.rsuser
+*.sln.docstates
+_ReSharper*/
+*.ncrunch*
+_NCrunch*/
+[Bb]enchmark[Dd]ot[Nn]et.[Aa]rtifacts/
+[Tt]est[Rr]esults/
+coverage/
+*.coverage
+*.coveragexml
+*.testlog
+
+# Local secrets, package output and OS/editor temporary files
+.env
+.env.*
+!.env.example
+*.pfx
+*.p12
+*.key
+*.pem
+*.nupkg
+*.snupkg
+.DS_Store
+Thumbs.db
+Desktop.ini
+*~
+*.swp
+*.swo
+
+# Local campaign configuration and tool installs
+config.yaml
+.tool-install/

.gitleaks.toml

@@ -0,0 +1,10 @@
+# Retain every default detector. This exact tensor fixture is not an API key.
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "Exact native/external tensor-name fixture, including its historical path"
+condition = "AND"
+paths = ['''(^|/)MagicQuant.Tests/ExternalBaselineTensorParityTests\.cs$''']
+regexTarget = "line"
+regexes = ['''^\s*var (native|external) = Metadata\(nextnLayers: 1, "token_embd\.weight", "blk\.0\.attn_q\.weight", "blk\.64\.nextn\.eh_proj\.weight"\);$''']

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Start with the [architecture map](docs/architecture.md), [configuration rules](docs/configuration.md), and the [research wiki](https://github.com/magiccodingman/MagicQuant). This repository implements benchmark-driven discovery; the `evolution` name survives as a compatibility alias.
+
+## Local workflow
+
+```sh
+dotnet restore MagicQuant.sln --locked-mode
+dotnet build MagicQuant.sln -c Debug --no-restore
+dotnet test MagicQuant.sln -c Debug --no-build
+dotnet build MagicQuant.sln -c Release --no-restore
+dotnet test MagicQuant.sln -c Release --no-build
+```
+
+CI runs both configurations on Linux and Windows with warnings treated as errors and locked package restores. Use `--filter FullyQualifiedName~YourTestClass` to focus a test run during development. Tests run serially because configuration and runtime registries are global. Source-contract regression tests assume the normal repository/build layout; run the suite from the checkout rather than copying the test DLL elsewhere.
+
+Keep personal settings in an ignored `config.local.yaml` and pass `--config` explicitly. Do not add machine paths or automatic DEBUG campaigns to `Program.cs`. Use IDE run arguments for your campaign. Never commit weights, runtime databases, exported GGUFs, credentials, or local logs.
+
+## Making a change
+
+- Keep commands focused on orchestration; extract cohesive policy or path logic into services when it can be tested independently.
+- Use existing baseline identity, effective-state, and path helpers. Do not duplicate database filenames, tensor-slot ordering, or custom-baseline normalization.
+- Explain why a non-obvious constraint exists in a comment. Avoid comments that merely restate a method call or retain obsolete blocks of disabled implementation.
+- When adding a config option, update the typed model, loader override if needed, commented default YAML, documentation, and a behavior test. Distinguish C# defaults from the distributed YAML profile.
+- Test observable behavior: boundary cases, context scoping, cache reuse/invalidation, ranking/tie rules, path resolution, or failure propagation. Avoid tests that only repeat the implementation's constants without exercising a contract.
+- Treat persisted IDs, database schemas, manifests, and artifact names as compatibility contracts. Provide an explicit migration plan for changes to them.
+
+For a bug fix, add a regression that fails without the fix. Tests that mutate `Config`, `Cache`, or registries must restore prior state in `finally`; use unique temporary roots. Keep unit tests free of network downloads, sudo, model quantization, and persistent changes to a developer's runtime.
+
+## Hardware integration changes
+
+Changes to conversion, quantization arguments, benchmark scheduling, or numerical selection need a small-model integration check in addition to unit tests. Record model identity, hardware, imatrix, dependency revisions, command/config, observed outputs, and before/after metrics. Use an isolated output directory. Do not claim full quantization parity from a passing unit suite.
+
+For documentation or path refactoring, verify examples against actual help and protect historical path rules. Avoid re-running expensive full campaigns when the changed behavior can be checked directly.
+
+## Pull request expectations
+
+Describe the concrete problem and resulting behavior, relevant compatibility effects, and validation performed. Separate numerical policy changes from mechanical cleanup when possible. Mention untested hardware/platform paths and any remaining compiler warnings. Prefer focused commits that can be reviewed without reconstructing the conversation that led to them.
+
+The maintainer still needs to choose a software license before an open-source release; do not infer one from generated model metadata or dependency licenses.
+
+See [testing and merge checks](docs/testing.md) for the manual small-model workflow,
+package lock updates, and required-check setup. [Worked examples](docs/extending.md)
+show how to add configuration and test native/process/path changes.
+
+## Repository layout and release safety
+
+Application projects are under `src/`; test projects are under `tests/`. Program guides belong in `docs/`; research explanations belong in `wiki/`. Use relative links so documentation remains useful in checkouts and forks. Source paths are separate from model/runtime data paths.
+
+Run the [installed-package checks](docs/testing.md#installed-package-and-release-checks) when changing paths, packaging, startup, or bundled files. Publication is controlled by [release branch automation](docs/releases.md). Never put NuGet keys or personal configuration into a workflow. Original contributions are accepted under the repository's AGPL-3.0-only license; retain third-party attribution.

Directory.Build.props

@@ -0,0 +1,5 @@
+<Project>
+  <PropertyGroup>
+    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
+  </PropertyGroup>
+</Project>