sparse-attention-fabric 0.1.0__tar.gz

sparse_attention_fabric-0.1.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes are recorded here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the structure of
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Planned
+
+- Publish controlled A100 evidence after the complete release validator passes.
+
+## [0.1.0] - 2026-08-29
+
+### Added
+
+- Exact immutable causal-window pattern and analytic block-row lowering.
+- Cached, inspectable execution planning across SDPA and FlexAttention.
+- PyTorch autograd-preserving public execution API with fail-closed validation.
+- Locked M0 benchmark matrix, fresh-process harness, raw JSONL schema, and strict
+  cross-record release validator.
+- Stock PyTorch 2.13 `varlen_attn` baseline with exact inclusive-window
+  translation, a static fullgraph compiled BHLD↔THD adapter, forward/backward
+  correctness gates, and explicit modeled conversion accounting.
+- Independent numerical and mask-membership correctness checks.
+- Deterministic, schema-validated A100 feasibility modeling that is explicitly
+  barred from measured-performance claims.
+- CPU contract CI, manual controlled-CUDA evidence workflow, packaging metadata,
+  and open-source governance files.
+
+### Security and reliability
+
+- Bounded all runtime caches and untrusted protocol inputs.
+- Made explicit overwrite atomic and safe against destination symlinks.
+- Pinned privileged Actions and release dependencies to immutable identities,
+  added provenance attestations, and separated semantic validation from origin
+  authentication.
+- Made CUDA mask-cache publication safe across producer and consumer streams
+  without adding synchronization to hot cache hits.
+- Staged release assets before immutable publication, upgraded maintained
+  Actions to Node 24, and excluded tests from the runtime wheel.
+
+### Known limitations
+
+- No controlled GPU measurement is included in this release.
+- CUDA execution is limited to the M0 support matrix documented in
+  `m0/README.md`.
+- ROCm, MPS, CPU execution, arbitrary sparsity, decode/KV cache, GQA/MQA, and
+  distributed attention are outside this release.

sparse_attention_fabric-0.1.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If this software helps your work, please cite this release and its exact evidence artifact."
+title: "Sparse Attention Fabric"
+type: software
+version: 0.1.0
+date-released: 2026-08-29
+license: Apache-2.0
+repository-code: "https://github.com/pocket20/sparse-attention-fabric"
+url: "https://github.com/pocket20/sparse-attention-fabric/releases/tag/v0.1.0"
+authors:
+  - name: "Sparse Attention Fabric contributors"
+abstract: >-
+  An evidence-first PyTorch execution planner and reproducible benchmark harness
+  for exact causal-window attention.
+keywords:
+  - sparse attention
+  - PyTorch
+  - CUDA
+  - benchmarking
+  - execution planning

sparse_attention_fabric-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,108 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people.
+- Respecting differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility and apologizing to those affected by our mistakes.
+- Focusing on what is best for the overall community.
+
+Examples of unacceptable behavior include:
+
+- Sexualized language or imagery and unwelcome sexual attention or advances.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting.
+
+## Enforcement responsibilities
+
+Community leaders are responsible for clarifying and enforcing standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to behavior they deem inappropriate, threatening, offensive, or
+harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are not
+aligned with this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and when an individual
+officially represents the community in public spaces.
+
+## Enforcement
+
+Report abusive, harassing, or otherwise unacceptable behavior privately using
+the repository's channel described in [SECURITY.md](SECURITY.md). All complaints
+will be reviewed and investigated promptly and fairly. Community leaders must
+respect the privacy and security of the reporter.
+
+## Enforcement guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community impact:** Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence:** A private, written warning providing clarity around the nature
+of the violation and an explanation of why the behavior was inappropriate. A
+public apology may be requested.
+
+### 2. Warning
+
+**Community impact:** A violation through a single incident or series of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period. This includes
+avoiding interactions in community spaces and external channels such as social
+media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary ban
+
+**Community impact:** A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any interaction or public communication
+with the community for a specified period. No public or private interaction with
+the people involved, including unsolicited interaction with those enforcing the
+Code of Conduct, is allowed during this period. Violating these terms may lead
+to a permanent ban.
+
+### 4. Permanent ban
+
+**Community impact:** A pattern of violating community standards, including
+sustained inappropriate behavior, harassment of an individual, or aggression
+toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).

sparse_attention_fabric-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for helping make sparse-attention execution easier to measure and use.
+Changes should make the implementation smaller, clearer, more correct, or more
+reproducible. A benchmark improvement without matched semantics is a regression.
+
+## Development setup
+
+Sparse Attention Fabric supports CPython 3.11 and 3.12. CPU contract work does
+not require PyTorch:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+python -m unittest discover -s tests -p 'test_*.py' -v
+```
+
+For CUDA work, first install the official PyTorch 2.13 build matched to the host,
+then use `python -m pip install --no-deps -e .` so environment setup does not
+silently replace the selected wheel.
+
+## Change rules
+
+- Keep the public pattern and planner API typed, narrow, and fail-closed.
+- Add a focused regression test for every behavior change.
+- Do not add a backend fallback unless its choice and costs are observable.
+- Do not reuse production mask construction in an independent correctness oracle.
+- Treat host synchronization, layout conversion, compilation, autotuning, and
+  mask construction as costs that must be assigned to an explicit timing scope.
+- Preserve failure rows and raw samples. Never trim data to improve a result.
+- Keep optional dependencies lazily imported so CPU planning remains usable.
+
+The M0 protocol is immutable. Any change to a case, threshold, implementation
+arm, timing rule, correctness rule, or canonical configuration requires a new
+suite ID, schema review, and changelog entry. Never update the locked fingerprint
+in isolation.
+
+## Pull requests
+
+Before opening a pull request:
+
+```bash
+python -m unittest discover -s tests -p 'test_*.py' -v
+python -m json.tool m0/core_cases.json >/dev/null
+python -m json.tool m0/result.schema.json >/dev/null
+python -m build
+python -m twine check dist/*
+```
+
+Describe user-visible behavior, compatibility, tests, and benchmark impact.
+Performance pull requests must attach machine-readable evidence or explicitly
+state that the proposed gain is unmeasured. Modeled estimates must be labeled as
+models and must include their assumptions.
+
+Small, single-purpose commits are preferred. Contributors certify the
+[Developer Certificate of Origin](https://developercertificate.org/) by adding
+`Signed-off-by` to commits (`git commit -s`).
+
+## Benchmark evidence
+
+Do not use pull-request runners for release performance claims. Use the manual,
+exclusive-GPU workflow described in [docs/benchmarking.md](docs/benchmarking.md),
+then attach its JSONL and summary without editing them. A negative or unsupported
+result is useful evidence and must remain visible.
+
+## Reporting vulnerabilities
+
+Do not disclose a suspected vulnerability in a public issue. Follow
+[SECURITY.md](SECURITY.md).

sparse_attention_fabric-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sparse_attention_fabric-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include CHANGELOG.md
+include CITATION.cff
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include LICENSE
+include NOTICE
+include README.md
+include SECURITY.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include m0 *.json *.md
+recursive-include requirements *.in *.lock
+recursive-include tests *.py

sparse_attention_fabric-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+Sparse Attention Fabric
+Copyright 2026 Sparse Attention Fabric contributors
+
+This product includes software developed by the Sparse Attention Fabric
+contributors.

sparse_attention_fabric-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: sparse-attention-fabric
+Version: 0.1.0
+Summary: Evidence-first execution planning for exact causal-window attention
+Author: Sparse Attention Fabric contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/pocket20/sparse-attention-fabric
+Project-URL: Documentation, https://github.com/pocket20/sparse-attention-fabric/tree/main/docs
+Project-URL: Repository, https://github.com/pocket20/sparse-attention-fabric.git
+Project-URL: Issues, https://github.com/pocket20/sparse-attention-fabric/issues
+Project-URL: Changelog, https://github.com/pocket20/sparse-attention-fabric/blob/main/CHANGELOG.md
+Keywords: attention,benchmarking,cuda,pytorch,sparse-attention
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <3.13,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Provides-Extra: validation
+Requires-Dist: jsonschema<5,>=4.23; extra == "validation"
+Provides-Extra: cuda
+Requires-Dist: torch<2.14,>=2.13; extra == "cuda"
+Provides-Extra: benchmark
+Requires-Dist: jsonschema<5,>=4.23; extra == "benchmark"
+Requires-Dist: torch<2.14,>=2.13; extra == "benchmark"
+Provides-Extra: dev
+Requires-Dist: build==1.3.0; extra == "dev"
+Requires-Dist: jsonschema==4.26.0; extra == "dev"
+Requires-Dist: ruff==0.16.5; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+Dynamic: license-file
+
+# Sparse Attention Fabric
+
+[![CI](https://github.com/pocket20/sparse-attention-fabric/actions/workflows/ci.yml/badge.svg)](https://github.com/pocket20/sparse-attention-fabric/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/pocket20/sparse-attention-fabric/blob/main/LICENSE)
+
+Sparse Attention Fabric is an evidence-first PyTorch execution planner for exact
+causal-window attention. The initial `0.1.0` release is intentionally narrow: it
+chooses among causal SDPA, masked SDPA, and compiled FlexAttention while exposing
+its decision and preserving PyTorch autograd.
+
+This release is an executable hypothesis, not a performance claim. No controlled
+GPU result is bundled yet. Numeric thresholds in the M0 protocol are
+pre-registered targets. `saf-m0-validate --release` checks a supplied matrix's
+structure and semantics but does not authenticate its origin; a result becomes
+publishable only after validation and independent GitHub-attestation verification
+against the exact controlled workflow, default-branch ref, and candidate commit.
+
+## What ships in 0.1.0
+
+- An immutable `CausalWindow` pattern with exact token and block semantics.
+- A small, inspectable, cached `ExecutionFabric` policy.
+- Fail-closed CUDA execution through public PyTorch APIs.
+- A locked 19-case, four-implementation benchmark matrix with 380 fresh-process rows.
+- Raw-sample JSONL evidence, a JSON Schema, correctness checks, and release gates.
+- A deterministic, explicitly non-release A100 feasibility model for hardware-free auditing.
+- CPU contract tests plus a manually dispatched A100 evidence workflow.
+
+M0 is not a general sparse tensor compiler, a custom CUDA kernel library, or an
+MoE runtime. See [the architecture](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/architecture.md) for the deliberate
+boundaries and the [competitive landscape](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/landscape.md) for the primary-source
+decision record. The [evidence-gated roadmap](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/roadmap.md) states what can follow a
+positive, negative, or invalid controlled run.
+
+## Install
+
+Planning and contract tests have no runtime dependency:
+
+```bash
+python -m pip install .
+```
+
+Evidence validation adds JSON Schema support:
+
+```bash
+python -m pip install '.[validation]'
+```
+
+CUDA execution requires the PyTorch 2.13 build appropriate for the machine. In
+controlled environments, install PyTorch from the official channel selected for
+the CUDA driver, then install this project without allowing pip to replace it:
+
+```bash
+python -m pip install --no-deps .
+python -c 'import torch; print(torch.__version__, torch.version.cuda)'
+```
+
+The `cuda` and `benchmark` extras express compatible version constraints, but
+they cannot choose the correct CUDA wheel index for a particular host.
+
+## Use
+
+```python
+from m0 import CausalWindow, ExecutionFabric
+
+fabric = ExecutionFabric(max_cache_entries=32)
+pattern = CausalWindow(window=512)
+output = fabric(query, key, value, pattern)
+plan = fabric.plan(
+    pattern,
+    sequence_length=query.shape[-2],
+    dtype=str(query.dtype).removeprefix("torch."),
+)
+print(plan.backend, plan.rationale)
+
+# Optional for a tight loop: validates once and retains metadata, not tensors.
+prepared = fabric.prepare(query, key, value, pattern)
+next_output = prepared(next_query, next_key, next_value)
+```
+
+Inputs must be contiguous CUDA `BHLD` tensors with FP16 or BF16 dtype, equal
+query/KV head counts and lengths, and head/value dimensions of 64 or 128.
+Unsupported inputs raise an error instead of silently changing semantics.
+Prepared calls reject a changed shape, stride, device, dtype, pattern, or
+autograd context; call `prepare` again when any execution metadata changes.
+The entry limit applies independently to plans, masks, compiled Flex functions,
+prepared executors, and device capabilities. Slow-path insertions evict the
+oldest entry; hot prepared-cache hits remain lock-free. Inspect the configured
+limit and current occupancy with `fabric.cache_info()`.
+
+For a complete projection-to-attention-to-output module, see the
+[Transformer-style integration example](https://github.com/pocket20/sparse-attention-fabric/blob/main/examples/transformer_attention.py).
+
+## Validate locally
+
+```bash
+python -m unittest discover -s tests -p 'test_*.py' -v
+python -m json.tool m0/core_cases.json >/dev/null
+python -m json.tool m0/result.schema.json >/dev/null
+python -m json.tool m0/feasibility.schema.json >/dev/null
+saf-m0 --help
+saf-m0-model --help
+saf-m0-validate --help
+```
+
+Run the full benchmark only on a controlled Linux CUDA host. The canonical
+protocol, operator attestations, commands, interpretation rules, and known
+limitations are in the [M0 evidence guide](https://github.com/pocket20/sparse-attention-fabric/blob/main/m0/README.md) and
+[benchmark operations guide](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/benchmarking.md).
+
+When the target GPU is unavailable, run `saf-m0-model` to audit exact pair
+counts, block rounding, visible storage, and peak-rate sensitivity envelopes. The
+[modeled-validation guide](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/MODELED_VALIDATION.md) states what the model can
+and cannot establish. Its output is structurally barred from release validation.
+
+## Evidence and claims
+
+Every release-quality performance statement must link to the immutable JSONL,
+validated summary, verified GitHub attestations, exact commit, hardware/software
+environment, and timing scope. A detached artifact or checksum is not proof of a
+controlled run. Unsupported, OOM, correctness-failure, and negative-performance
+rows are part of the result and must not be removed. Modeled hardware results
+may guide engineering but may never be reported as measured CUDA performance.
+The direct baselines are SDPA, generic FlexAttention, and native PyTorch
+`varlen_attn`; the latter compiles its complete BHLD-to-THD-to-native-call-to-BHLD
+adapter and keeps all required layout work inside every timed sample. NATTEN is an external head-to-head
+prerequisite for any future ecosystem-wide or best-in-class claim, not a
+package dependency.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](https://github.com/pocket20/sparse-attention-fabric/blob/main/CONTRIBUTING.md) for development and benchmark rules,
+[SECURITY.md](https://github.com/pocket20/sparse-attention-fabric/blob/main/SECURITY.md) for private vulnerability reporting, and
+[docs/releasing.md](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/releasing.md) for the release process. The
+[0.1.0 assurance record](https://github.com/pocket20/sparse-attention-fabric/blob/main/docs/release-assurance.md) documents the pre-release
+security and red-team disposition. Participation is governed by the
+[Contributor Covenant](https://github.com/pocket20/sparse-attention-fabric/blob/main/CODE_OF_CONDUCT.md).
+
+Licensed under Apache-2.0. See [LICENSE](https://github.com/pocket20/sparse-attention-fabric/blob/main/LICENSE) and [NOTICE](https://github.com/pocket20/sparse-attention-fabric/blob/main/NOTICE).