authorized-recall 0.1.0__tar.gz

authorized_recall-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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.

authorized_recall-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: authorized-recall
+Version: 0.1.0
+Summary: Authorized Recall@K — retrieval quality measured over the subset a principal is permitted to use
+Author: Alexander Chernov
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/agentic-datasets/reference
+Project-URL: Documentation, https://agenticdatasets.org/reference/
+Project-URL: Source, https://github.com/agentic-datasets/reference/tree/main/packages/authorized-recall
+Keywords: information retrieval,evaluation metric,authorization,access control,multi-tenant,RAG,ABAC,RBAC
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Authorized Recall@K
+
+**Retrieval quality measured over the subset a principal may actually use.**
+
+This package has no dependency on the rest of the repository. The metric takes
+a predicate, not a `Principal`, so a system using RBAC, ABAC, row-level
+security or per-tenant vector namespaces can adopt the measurement without
+adopting anything else here.
+
+```bash
+pip install authorized-recall
+python -m authorized_recall           # or: authorized-recall
+```
+
+---
+
+## Why
+
+A retrieval system that surfaces a dataset the caller is not permitted to use
+has not helped them. They cannot act on it; the only thing that changed is that
+they now know it exists. Standard Recall@K scores that as a success, and it has
+also spent one of the K slots doing it.
+
+In the corpus measured here, **68.8% of what retrieval returns is unusable to
+the principal who asked**, and Recall@K cannot see it.
+
+## Definition
+
+Let
+
+- $D$ — the corpus,
+- $q$ — a query, with relevant set $R(q) \subseteq D$,
+- $p$ — a principal, with authorization predicate $A_p : D \to \{0,1\}$,
+- $L_K(q,p)$ — the ordered list of at most $K$ items the system returns.
+
+The **authorized relevant set** is
+
+$$R_A(q,p) = \{\, d \in R(q) : A_p(d) = 1 \,\}$$
+
+and
+
+$$\mathrm{ARecall}@K(q,p) = \frac{|R_A(q,p) \cap L_K(q,p)|}{|R_A(q,p)|},
+\qquad \mathrm{ARecall}@K \triangleq 1 \ \text{ when } R_A = \emptyset .$$
+
+Compare
+
+$$\mathrm{Recall}@K(q) = \frac{|R(q) \cap L_K|}{|R(q)|} .$$
+
+**When $A_p \equiv 1$, $\mathrm{ARecall}@K = \mathrm{Recall}@K$.** The metric is
+a strict generalisation, not a different measurement.
+
+### Two conventions, stated because they change the mean
+
+1. $R_A = \emptyset \Rightarrow \mathrm{ARecall}@K = 1$. The system cannot be
+   faulted for failing to surface what it must not surface. Over a population
+   containing such pairs this inflates the mean, so report the restricted mean
+   — over pairs with $R_A \neq \emptyset$ — alongside it. The experiment here
+   prints both.
+2. Retrieved-but-unauthorized items are neither credited nor penalised inside
+   ARecall. They are a separate quantity:
+
+$$U@K(q,p) = \frac{|\{\, d \in L_K : A_p(d) = 0 \,\}|}{K}$$
+
+## Where the filter sits
+
+ARecall is computed over the list the system **returns**, so it is sensitive to
+whether truncation happens before or after the authorization filter:
+
+$$L_K^{\text{post}} = \sigma_{A_p}\big(\mathrm{top}_K(\mathrm{rank}(D))\big)
+\qquad
+L_K^{\text{pre}} = \mathrm{top}_K\big(\sigma_{A_p}(\mathrm{rank}(D))\big)$$
+
+**Claim.** $L_K^{\text{post}} \subseteq L_K^{\text{pre}}$ for every ranking,
+$K$ and $A_p$, hence
+
+$$\Delta@K = \mathrm{ARecall}^{\text{pre}}@K - \mathrm{ARecall}^{\text{post}}@K \;\geq\; 0 .$$
+
+*Proof.* Filtering preserves relative order. An item in $L_K^{\text{post}}$ is
+authorized and appears within the first $K$ positions of the ranking, so at
+most $K-1$ items precede it, so at most $K-1$ *authorized* items precede it,
+so it appears within the first $K$ authorized items — which is
+$L_K^{\text{pre}}$. ∎
+
+The gap is therefore non-negative by construction rather than by luck of the
+corpus. What the corpus determines is its *size*.
+
+## Measured
+
+40 synthetic datasets over 8 domains, 24 queries, 4 authorization profiles,
+96 query-principal pairs. Relevance by construction: a dataset is relevant to a
+query when it is in the query's domain. Retrieval is TF-IDF cosine.
+
+```
+  K   Recall  ARecall  ARecall    gap  unusable
+                 post      pre         in top-K
+  1    0.200    0.750    0.750 +0.000     68.8%
+  3    0.483    0.835    0.863 +0.027     68.8%
+  5    0.867    0.954    0.988 +0.033     68.5%
+ 10    1.000    1.000    1.000 +0.000     39.1%
+```
+
+Restricted to the 30 pairs with $R_A \neq \emptyset$:
+
+```
+  K  ARecall post  ARecall pre     gap
+  1         0.200        0.200  +0.000
+  3         0.473        0.560  +0.087
+  5         0.853        0.960  +0.107
+ 10         1.000        1.000  +0.000
+```
+
+**At K=5, moving the filter ahead of truncation takes ARecall@5 from 0.853 to
+0.960 (+0.107). Recall@5 stays at 0.867 and cannot see the difference.**
+
+## What this does and does not establish
+
+The absolute values belong to this corpus: relevance is by construction, the
+retriever is TF-IDF, and MRR is 1.000, so the retrieval task is easy. A harder
+corpus or a better retriever moves all three columns.
+
+The *gap* is what the metric was defined to isolate, and the claim above is
+that it is a property of filter placement rather than of retrieval quality. The
+proof makes its sign certain; the experiment gives its size in one setting.
+
+Applying it to a real corpus with real authorization data is the obvious next
+measurement, and this package is separable precisely so that someone else can
+do it.

authorized_recall-0.1.0/README.md

@@ -0,0 +1,127 @@
+# Authorized Recall@K
+
+**Retrieval quality measured over the subset a principal may actually use.**
+
+This package has no dependency on the rest of the repository. The metric takes
+a predicate, not a `Principal`, so a system using RBAC, ABAC, row-level
+security or per-tenant vector namespaces can adopt the measurement without
+adopting anything else here.
+
+```bash
+pip install authorized-recall
+python -m authorized_recall           # or: authorized-recall
+```
+
+---
+
+## Why
+
+A retrieval system that surfaces a dataset the caller is not permitted to use
+has not helped them. They cannot act on it; the only thing that changed is that
+they now know it exists. Standard Recall@K scores that as a success, and it has
+also spent one of the K slots doing it.
+
+In the corpus measured here, **68.8% of what retrieval returns is unusable to
+the principal who asked**, and Recall@K cannot see it.
+
+## Definition
+
+Let
+
+- $D$ — the corpus,
+- $q$ — a query, with relevant set $R(q) \subseteq D$,
+- $p$ — a principal, with authorization predicate $A_p : D \to \{0,1\}$,
+- $L_K(q,p)$ — the ordered list of at most $K$ items the system returns.
+
+The **authorized relevant set** is
+
+$$R_A(q,p) = \{\, d \in R(q) : A_p(d) = 1 \,\}$$
+
+and
+
+$$\mathrm{ARecall}@K(q,p) = \frac{|R_A(q,p) \cap L_K(q,p)|}{|R_A(q,p)|},
+\qquad \mathrm{ARecall}@K \triangleq 1 \ \text{ when } R_A = \emptyset .$$
+
+Compare
+
+$$\mathrm{Recall}@K(q) = \frac{|R(q) \cap L_K|}{|R(q)|} .$$
+
+**When $A_p \equiv 1$, $\mathrm{ARecall}@K = \mathrm{Recall}@K$.** The metric is
+a strict generalisation, not a different measurement.
+
+### Two conventions, stated because they change the mean
+
+1. $R_A = \emptyset \Rightarrow \mathrm{ARecall}@K = 1$. The system cannot be
+   faulted for failing to surface what it must not surface. Over a population
+   containing such pairs this inflates the mean, so report the restricted mean
+   — over pairs with $R_A \neq \emptyset$ — alongside it. The experiment here
+   prints both.
+2. Retrieved-but-unauthorized items are neither credited nor penalised inside
+   ARecall. They are a separate quantity:
+
+$$U@K(q,p) = \frac{|\{\, d \in L_K : A_p(d) = 0 \,\}|}{K}$$
+
+## Where the filter sits
+
+ARecall is computed over the list the system **returns**, so it is sensitive to
+whether truncation happens before or after the authorization filter:
+
+$$L_K^{\text{post}} = \sigma_{A_p}\big(\mathrm{top}_K(\mathrm{rank}(D))\big)
+\qquad
+L_K^{\text{pre}} = \mathrm{top}_K\big(\sigma_{A_p}(\mathrm{rank}(D))\big)$$
+
+**Claim.** $L_K^{\text{post}} \subseteq L_K^{\text{pre}}$ for every ranking,
+$K$ and $A_p$, hence
+
+$$\Delta@K = \mathrm{ARecall}^{\text{pre}}@K - \mathrm{ARecall}^{\text{post}}@K \;\geq\; 0 .$$
+
+*Proof.* Filtering preserves relative order. An item in $L_K^{\text{post}}$ is
+authorized and appears within the first $K$ positions of the ranking, so at
+most $K-1$ items precede it, so at most $K-1$ *authorized* items precede it,
+so it appears within the first $K$ authorized items — which is
+$L_K^{\text{pre}}$. ∎
+
+The gap is therefore non-negative by construction rather than by luck of the
+corpus. What the corpus determines is its *size*.
+
+## Measured
+
+40 synthetic datasets over 8 domains, 24 queries, 4 authorization profiles,
+96 query-principal pairs. Relevance by construction: a dataset is relevant to a
+query when it is in the query's domain. Retrieval is TF-IDF cosine.
+
+```
+  K   Recall  ARecall  ARecall    gap  unusable
+                 post      pre         in top-K
+  1    0.200    0.750    0.750 +0.000     68.8%
+  3    0.483    0.835    0.863 +0.027     68.8%
+  5    0.867    0.954    0.988 +0.033     68.5%
+ 10    1.000    1.000    1.000 +0.000     39.1%
+```
+
+Restricted to the 30 pairs with $R_A \neq \emptyset$:
+
+```
+  K  ARecall post  ARecall pre     gap
+  1         0.200        0.200  +0.000
+  3         0.473        0.560  +0.087
+  5         0.853        0.960  +0.107
+ 10         1.000        1.000  +0.000
+```
+
+**At K=5, moving the filter ahead of truncation takes ARecall@5 from 0.853 to
+0.960 (+0.107). Recall@5 stays at 0.867 and cannot see the difference.**
+
+## What this does and does not establish
+
+The absolute values belong to this corpus: relevance is by construction, the
+retriever is TF-IDF, and MRR is 1.000, so the retrieval task is easy. A harder
+corpus or a better retriever moves all three columns.
+
+The *gap* is what the metric was defined to isolate, and the claim above is
+that it is a property of filter placement rather than of retrieval quality. The
+proof makes its sign certain; the experiment gives its size in one setting.
+
+Applying it to a real corpus with real authorization data is the obvious next
+measurement, and this package is separable precisely so that someone else can
+do it.

authorized_recall-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "authorized-recall"
+version = "0.1.0"
+description = "Authorized Recall@K — retrieval quality measured over the subset a principal is permitted to use"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Alexander Chernov" }]
+keywords = [
+    "information retrieval", "evaluation metric", "authorization",
+    "access control", "multi-tenant", "RAG", "ABAC", "RBAC",
+]
+# No "License ::" classifier: PEP 639 supersedes them with the expression above.
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Intended Audience :: Science/Research",
+]
+
+# No dependencies, and that is the point: the metric is a property of
+# policy-conditioned retrieval, not of any particular stack. It takes an
+# authorization predicate, so a system using RBAC, ABAC, row-level security or
+# per-tenant vector namespaces can adopt the measurement without adopting
+# anything else.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/agentic-datasets/reference"
+Documentation = "https://agenticdatasets.org/reference/"
+Source = "https://github.com/agentic-datasets/reference/tree/main/packages/authorized-recall"
+
+[project.scripts]
+authorized-recall = "authorized_recall.experiment:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

authorized_recall-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

authorized_recall-0.1.0/src/authorized_recall/__init__.py

@@ -0,0 +1,28 @@
+"""Authorized Recall@K — retrieval quality over the subset a principal may use.
+
+Self-contained: nothing in this package imports the rest of the repository, so
+the metric can be adopted without adopting the control plane. See README.md
+here for the definition and the non-negativity proof for the pre/post-filter
+gap.
+"""
+
+from .metric import (
+    Authorized,
+    authorized_recall_at_k,
+    ndcg_at_k,
+    post_filter,
+    pre_filter,
+    precision_at_k,
+    recall_at_k,
+    reciprocal_rank,
+    unusable_fraction_at_k,
+)
+from .retrieval import TfIdfIndex
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Authorized", "TfIdfIndex", "__version__", "authorized_recall_at_k", "ndcg_at_k",
+    "post_filter", "pre_filter", "precision_at_k", "recall_at_k",
+    "reciprocal_rank", "unusable_fraction_at_k",
+]

authorized_recall-0.1.0/src/authorized_recall/__main__.py

@@ -0,0 +1,4 @@
+from .experiment import main
+
+if __name__ == "__main__":
+    main()

authorized_recall-0.1.0/src/authorized_recall/corpus.py

@@ -0,0 +1,160 @@
+"""The discovery corpus. Deterministic, so the numbers are reproducible.
+
+Forty datasets across eight domains, twenty-four queries, four authorization
+profiles. Relevance is defined by construction -- a dataset is relevant to a
+query if it belongs to the query's domain -- because a ground truth argued
+after the fact is a ground truth fitted to the retriever.
+
+`build()` returns the corpus in memory, so the experiment runs with no data
+files present. `python -m authorized_recall.corpus` also writes
+it to `evals/datasets/*.json`, which are committed as the record of what was
+measured.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+DEFAULT_OUT = Path("corpus")
+
+DOMAINS = {
+    "purification": {
+        "vocabulary": "purification recovery yield elution buffer capture polish load",
+        "facets": ["batch records", "step yields", "buffer conditions", "load challenges", "elution pools"],
+        "sensitivity": "internal",
+    },
+    "chromatography": {
+        "vocabulary": "chromatography column peak resolution retention gradient pooling",
+        "facets": ["peak tables", "column performance", "gradient profiles", "pooling decisions", "resolution trends"],
+        "sensitivity": "internal",
+    },
+    "fermentation": {
+        "vocabulary": "fermentation bioreactor viability titer feed dissolved oxygen",
+        "facets": ["viability curves", "titer profiles", "feed schedules", "oxygen transfer", "harvest criteria"],
+        "sensitivity": "internal",
+    },
+    "analytics": {
+        "vocabulary": "assay analytical potency purity impurity release specification",
+        "facets": ["potency assays", "purity results", "impurity profiles", "release testing", "specification limits"],
+        "sensitivity": "confidential",
+    },
+    "clinical": {
+        "vocabulary": "clinical subject endpoint adverse dose cohort visit",
+        "facets": ["subject observations", "endpoint summaries", "adverse events", "dose cohorts", "visit schedules"],
+        "sensitivity": "restricted",
+    },
+    "supply": {
+        "vocabulary": "supply inventory lot shipment warehouse cold chain logistics",
+        "facets": ["lot inventory", "shipment tracking", "cold chain excursions", "warehouse stock", "logistics routes"],
+        "sensitivity": "internal",
+    },
+    "equipment": {
+        "vocabulary": "equipment calibration maintenance asset downtime utilisation sensor",
+        "facets": ["calibration records", "maintenance logs", "downtime events", "asset utilisation", "sensor streams"],
+        "sensitivity": "internal",
+    },
+    "quality": {
+        "vocabulary": "quality deviation capa audit complaint change control batch disposition",
+        "facets": ["deviations", "CAPA records", "audit findings", "complaints", "batch disposition"],
+        "sensitivity": "confidential",
+    },
+}
+
+CAPABILITIES = ["search", "aggregate", "compare", "summarize"]
+
+# principal class -> domains it holds capabilities on
+PROFILES = {
+    "process-engineer": ["purification", "chromatography", "fermentation", "equipment"],
+    "analyst": ["analytics", "chromatography", "quality"],
+    "clinical-reviewer": ["clinical", "analytics"],
+    "external-auditor": ["quality"],
+}
+
+CLEARANCE = {
+    "process-engineer": "confidential",
+    "analyst": "confidential",
+    "clinical-reviewer": "restricted",
+    "external-auditor": "internal",
+}
+
+
+def build() -> tuple[list[dict], list[dict], dict]:
+    datasets: list[dict] = []
+    for domain, spec in DOMAINS.items():
+        for index, facet in enumerate(spec["facets"], start=1):
+            datasets.append(
+                {
+                    "dataset": f"{domain}-{facet.replace(' ', '-').lower()}",
+                    "domain": domain,
+                    "version": "2026.09.01",
+                    "revision": f"rev-{domain}-{index:02d}",
+                    "schema_version": "1",
+                    "description": f"{facet.capitalize()} for {domain}: {spec['vocabulary']}.",
+                    "schemas": [facet.replace(" ", "_")],
+                    "capabilities": [
+                        {
+                            "name": name,
+                            "effect": "read" if name in ("search", "compare") else "compute",
+                            "sensitivity": spec["sensitivity"],
+                            "description": f"{name} over {facet} in {domain}",
+                        }
+                        for name in CAPABILITIES
+                    ],
+                    "prohibited": ["delete_source", "bypass_governance"],
+                    "policies": [f"POL-{domain.upper()[:4]}-001"],
+                    "freshness": {"maximum_age_s": 86400},
+                    "age_s": 3600,
+                    "provenance": {"system": "volume", "source": "synthetic"},
+                }
+            )
+
+    queries: list[dict] = []
+    for domain, spec in DOMAINS.items():
+        for facet in spec["facets"][:3]:
+            queries.append(
+                {
+                    "query": f"what do the {facet} tell us about {spec['vocabulary'].split()[1]}",
+                    "domain": domain,
+                    "relevant": [d["dataset"] for d in datasets if d["domain"] == domain],
+                }
+            )
+
+    profiles = {
+        name: {
+            "principal_class": name,
+            "clearance": CLEARANCE[name],
+            "grants": {
+                d["dataset"]: CAPABILITIES
+                for d in datasets
+                if d["domain"] in domains
+            },
+        }
+        for name, domains in PROFILES.items()
+    }
+    return datasets, queries, profiles
+
+
+def main(out: Path | str | None = None) -> None:
+    import argparse
+
+    if out is None:
+        parser = argparse.ArgumentParser(prog="authorized_recall.corpus")
+        parser.add_argument("--out", default=str(DEFAULT_OUT),
+                            help="directory to write corpus.json, queries.json "
+                                 "and profiles.json into")
+        out = parser.parse_args().out
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    datasets, queries, profiles = build()
+    (out / "corpus.json").write_text(json.dumps({"datasets": datasets}, indent=2) + "\n")
+    (out / "queries.json").write_text(json.dumps({"queries": queries}, indent=2) + "\n")
+    (out / "profiles.json").write_text(json.dumps({"profiles": profiles}, indent=2) + "\n")
+    print(
+        f"{len(datasets)} datasets across {len(DOMAINS)} domains, "
+        f"{len(queries)} queries, {len(profiles)} authorization profiles"
+    )
+
+
+if __name__ == "__main__":
+    main()

authorized_recall-0.1.0/src/authorized_recall/experiment.py

@@ -0,0 +1,205 @@
+"""The Authorized Recall@K measurement.
+
+    python -m authorized_recall
+
+Runs on the in-memory corpus by default, so it needs no data files. `--json`
+reads the committed `evals/datasets/*.json` instead; both produce the same
+numbers, because they come from the same generator.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+from pathlib import Path
+from typing import Callable
+
+from .corpus import CAPABILITIES, build
+from .metric import (
+    authorized_recall_at_k,
+    ndcg_at_k,
+    post_filter,
+    pre_filter,
+    precision_at_k,
+    recall_at_k,
+    reciprocal_rank,
+    unusable_fraction_at_k,
+)
+from .retrieval import TfIdfIndex
+
+KS = (1, 3, 5, 10)
+
+
+def _load_from_json(data_dir: Path) -> tuple[list[dict], list[dict], dict]:
+    corpus = json.loads((data_dir / "corpus.json").read_text())["datasets"]
+    queries = json.loads((data_dir / "queries.json").read_text())["queries"]
+    profiles = json.loads((data_dir / "profiles.json").read_text())["profiles"]
+    return corpus, queries, profiles
+
+
+def _document(dataset: dict) -> str:
+    """The text a dataset is indexed under.
+
+    Identical to `descriptor.DatasetDescriptor.text` in the reference
+    implementation. It has to be: this experiment and the one reachable through
+    the control plane are the same experiment, and two document constructions
+    would give two nDCG columns both claiming to be it.
+    """
+    parts = [dataset["dataset"].replace("-", " "), dataset.get("description", "")]
+    parts += [c["name"].replace("_", " ") for c in dataset.get("capabilities", ())]
+    parts += [c.get("description", "") for c in dataset.get("capabilities", ())]
+    parts += [s.replace("_", " ") for s in dataset.get("schemas", ())]
+    return " ".join(p for p in parts if p)
+
+
+def _predicate(profile: dict) -> Callable[[str], bool]:
+    """A profile becomes a predicate. Nothing downstream knows what a principal is."""
+    granted = set(profile["grants"])
+    return lambda dataset_id: dataset_id in granted
+
+
+def run(from_json: Path | str | None = None) -> dict:
+    """Measure. Builds the corpus in memory unless a data directory is given.
+
+    Deliberately no default path: this package ships no data and does not know
+    where a repository put any. `from_json` exists so a committed corpus can be
+    checked against the generator.
+    """
+    datasets, queries, profiles = (
+        _load_from_json(Path(from_json)) if from_json else build()
+    )
+    index = TfIdfIndex({d["dataset"]: _document(d) for d in datasets})
+    pool = len(datasets)
+
+    rows: dict[int, dict[str, list[float]]] = {
+        k: {key: [] for key in
+            ("recall", "arecall_post", "arecall_pre", "precision", "ndcg",
+             "unusable", "arecall_post_nz", "arecall_pre_nz")}
+        for k in KS
+    }
+    mrr: list[float] = []
+    unauthorized_relevant = total_relevant = 0
+
+    for query in queries:
+        relevant = query["relevant"]
+        ranking = index.rank(query["query"], k=pool)
+        mrr.append(reciprocal_rank(ranking, relevant))
+        for profile in profiles.values():
+            authorized = _predicate(profile)
+            authorized_relevant = [d for d in relevant if authorized(d)]
+            total_relevant += len(relevant)
+            unauthorized_relevant += len(relevant) - len(authorized_relevant)
+            for k in KS:
+                post = post_filter(ranking, authorized, k)
+                pre = pre_filter(ranking, authorized, k)
+                r = rows[k]
+                r["recall"].append(recall_at_k(ranking, relevant, k))
+                r["precision"].append(precision_at_k(ranking, relevant, k))
+                r["ndcg"].append(ndcg_at_k(ranking, relevant, k))
+                r["unusable"].append(unusable_fraction_at_k(ranking, authorized, k))
+                r["arecall_post"].append(
+                    authorized_recall_at_k(post, relevant, authorized, k)
+                )
+                r["arecall_pre"].append(
+                    authorized_recall_at_k(pre, relevant, authorized, k)
+                )
+                if authorized_relevant:
+                    r["arecall_post_nz"].append(r["arecall_post"][-1])
+                    r["arecall_pre_nz"].append(r["arecall_pre"][-1])
+
+    results = {}
+    for k in KS:
+        r = rows[k]
+        results[k] = {
+            "recall": statistics.mean(r["recall"]),
+            "arecall_post": statistics.mean(r["arecall_post"]),
+            "arecall_pre": statistics.mean(r["arecall_pre"]),
+            "precision": statistics.mean(r["precision"]),
+            "ndcg": statistics.mean(r["ndcg"]),
+            "unusable": statistics.mean(r["unusable"]),
+            "arecall_post_nonempty": statistics.mean(r["arecall_post_nz"]),
+            "arecall_pre_nonempty": statistics.mean(r["arecall_pre_nz"]),
+            "n_nonempty": len(r["arecall_pre_nz"]),
+        }
+        results[k]["gap"] = results[k]["arecall_pre"] - results[k]["arecall_post"]
+        results[k]["gap_nonempty"] = (
+            results[k]["arecall_pre_nonempty"] - results[k]["arecall_post_nonempty"]
+        )
+    return {
+        "datasets": len(datasets),
+        "queries": len(queries),
+        "profiles": len(profiles),
+        "pairs": len(queries) * len(profiles),
+        "unauthorized_relevant": unauthorized_relevant,
+        "total_relevant": total_relevant,
+        "mrr": statistics.mean(mrr),
+        "k": results,
+    }
+
+
+def report(out: dict) -> str:
+    lines = [
+        f"corpus: {out['datasets']} datasets, {out['queries']} queries, "
+        f"{out['profiles']} authorization profiles ({out['pairs']} query-principal pairs)",
+        f"relevant-but-unauthorized pairs: {out['unauthorized_relevant']}/"
+        f"{out['total_relevant']} "
+        f"({out['unauthorized_relevant'] / out['total_relevant']:.1%})",
+        f"MRR (authorization-blind): {out['mrr']:.3f}",
+        "",
+        f"{'K':>3}  {'Recall':>7} {'ARecall':>8} {'ARecall':>8} {'gap':>6}  "
+        f"{'P@K':>6} {'nDCG':>6} {'unusable':>8}",
+        f"{'':>3}  {'':>7} {'post':>8} {'pre':>8} {'':>6}  {'':>6} {'':>6} {'in top-K':>8}",
+    ]
+    for k in KS:
+        v = out["k"][k]
+        lines.append(
+            f"{k:>3}  {v['recall']:>7.3f} {v['arecall_post']:>8.3f} "
+            f"{v['arecall_pre']:>8.3f} {v['gap']:>+6.3f}  "
+            f"{v['precision']:>6.3f} {v['ndcg']:>6.3f} {v['unusable']:>8.1%}"
+        )
+    n = out["k"][KS[0]]["n_nonempty"]
+    lines += [
+        "",
+        f"excluding query-principal pairs where nothing relevant is authorized "
+        f"(n={n} of {out['pairs']}):",
+        f"{'K':>3}  {'ARecall post':>12} {'ARecall pre':>12} {'gap':>7}",
+    ]
+    for k in KS:
+        v = out["k"][k]
+        lines.append(
+            f"{k:>3}  {v['arecall_post_nonempty']:>12.3f} "
+            f"{v['arecall_pre_nonempty']:>12.3f} {v['gap_nonempty']:>+7.3f}"
+        )
+    five = out["k"][5]
+    lines += [
+        "",
+        "At K=5, moving the authorization filter ahead of truncation changes",
+        f"Authorized Recall@5 from {five['arecall_post_nonempty']:.3f} to "
+        f"{five['arecall_pre_nonempty']:.3f} ({five['gap_nonempty']:+.3f}) on the "
+        f"{five['n_nonempty']} pairs where anything",
+        f"relevant is authorized at all, while plain Recall@5 stays at "
+        f"{five['recall']:.3f} and cannot",
+        "see the difference. The gap's sign is guaranteed by the ordering argument in",
+        "this package's README; its size is what the corpus determines.",
+    ]
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="authorized-recall")
+    parser.add_argument("--json", metavar="DIR", default=None,
+                        help="read corpus.json, queries.json and profiles.json "
+                             "from DIR instead of building the corpus in memory")
+    parser.add_argument("--emit", metavar="PATH",
+                        help="write the result dictionary as JSON")
+    args = parser.parse_args()
+    out = run(from_json=args.json)
+    print(report(out))
+    if args.emit:
+        Path(args.emit).write_text(
+            json.dumps({"k": {str(k): v for k, v in out["k"].items()},
+                        **{x: out[x] for x in
+                           ("datasets", "queries", "profiles", "pairs", "mrr")}},
+                       indent=2) + "\n"
+        )

authorized_recall-0.1.0/src/authorized_recall/metric.py

@@ -0,0 +1,129 @@
+"""Authorized Recall@K, defined over a predicate rather than over a control plane.
+
+The metric takes `authorized: Callable[[str], bool]`, not a `Principal`, and
+nothing else in this package imports the reference implementation. That is
+deliberate: the quantity is a property of policy-conditioned retrieval, not of
+this architecture, and a system with RBAC, ABAC, row-level security or a
+multi-tenant vector store can use it without adopting anything here.
+
+See README.md in this directory for the mathematical definition and for the
+proof that the pre/post-filter gap is non-negative.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable, Iterable, Sequence
+
+__all__ = [
+    "Authorized",
+    "recall_at_k",
+    "authorized_recall_at_k",
+    "precision_at_k",
+    "reciprocal_rank",
+    "ndcg_at_k",
+    "unusable_fraction_at_k",
+    "post_filter",
+    "pre_filter",
+]
+
+Authorized = Callable[[str], bool]
+
+
+def recall_at_k(retrieved: Sequence[str], relevant: Iterable[str], k: int) -> float:
+    """|R ∩ L_K| / |R|. Authorization-blind, and 1.0 on an empty relevant set."""
+    rel = set(relevant)
+    if not rel:
+        return 1.0
+    return len(rel & set(retrieved[:k])) / len(rel)
+
+
+def authorized_recall_at_k(
+    retrieved: Sequence[str],
+    relevant: Iterable[str],
+    authorized: Authorized,
+    k: int,
+) -> float:
+    """|R_A ∩ L_K| / |R_A|, where R_A = { d ∈ R : authorized(d) }.
+
+    Recall over the subset the caller may actually use. Plain Recall@K counts a
+    retrieved item the caller cannot touch as a success; it is not one, and it
+    has spent one of the K slots.
+
+    Two conventions, decided rather than left to fall out of the arithmetic:
+
+    * **R_A empty → 1.0.** The system cannot be faulted for failing to surface
+      what it must not surface. This inflates the mean over a population
+      containing such pairs, so report the restricted mean alongside it.
+    * **Retrieved-but-unauthorized items are neither credited nor penalised
+      here.** They are a separate quantity, `unusable_fraction_at_k`.
+
+    When `authorized` is identically true this equals `recall_at_k`.
+    """
+    rel = set(relevant)
+    authorized_relevant = {d for d in rel if authorized(d)}
+    if not authorized_relevant:
+        return 1.0
+    return len(authorized_relevant & set(retrieved[:k])) / len(authorized_relevant)
+
+
+def unusable_fraction_at_k(
+    retrieved: Sequence[str], authorized: Authorized, k: int
+) -> float:
+    """Fraction of the K returned slots the caller cannot act on.
+
+    Reported separately from ARecall because it answers a different question:
+    not "did we find what they can use" but "how much of the answer was noise
+    to them".
+    """
+    if k == 0:
+        return 0.0
+    window = retrieved[:k]
+    return sum(1 for d in window if not authorized(d)) / k
+
+
+def precision_at_k(retrieved: Sequence[str], relevant: Iterable[str], k: int) -> float:
+    rel = set(relevant)
+    return len(rel & set(retrieved[:k])) / k if k else 0.0
+
+
+def reciprocal_rank(retrieved: Sequence[str], relevant: Iterable[str]) -> float:
+    rel = set(relevant)
+    for i, item in enumerate(retrieved, start=1):
+        if item in rel:
+            return 1.0 / i
+    return 0.0
+
+
+def ndcg_at_k(retrieved: Sequence[str], relevant: Iterable[str], k: int) -> float:
+    rel = set(relevant)
+    dcg = sum(
+        1.0 / math.log2(i + 1)
+        for i, item in enumerate(retrieved[:k], start=1)
+        if item in rel
+    )
+    ideal = sum(1.0 / math.log2(i + 1) for i in range(1, min(len(rel), k) + 1))
+    return dcg / ideal if ideal else 0.0
+
+
+# -- where the filter sits ------------------------------------------------
+#
+# The two arrangements the experiment compares. They differ only in whether
+# truncation happens before or after the authorization filter, and that
+# difference is the whole finding.
+
+def post_filter(ranking: Sequence[str], authorized: Authorized, k: int) -> list[str]:
+    """Truncate, then filter. The naive arrangement: unusable items occupy slots."""
+    return [d for d in ranking[:k] if authorized(d)]
+
+
+def pre_filter(ranking: Sequence[str], authorized: Authorized, k: int) -> list[str]:
+    """Filter, then truncate. K slots of usable answers.
+
+    `pre_filter` returns a superset of `post_filter` for every ranking, k and
+    predicate, because filtering preserves relative order: the authorized items
+    within the first K of the ranking are among the first K authorized items of
+    the ranking. That is why the measured gap is non-negative by construction
+    and not an artefact of the corpus.
+    """
+    return [d for d in ranking if authorized(d)][:k]

authorized_recall-0.1.0/src/authorized_recall/retrieval.py

@@ -0,0 +1,43 @@
+"""A TF-IDF index, so the package measures something without pulling in a retriever.
+
+Deliberately plain. The metric is a property of where the authorization filter
+sits, and a stronger retriever moves every column together -- so the retriever
+here only has to be reproducible, which an embedding model would not be.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import Mapping
+
+__all__ = ["TfIdfIndex"]
+
+_TOKEN = re.compile(r"[a-z0-9]+")
+
+
+class TfIdfIndex:
+    def __init__(self, documents: Mapping[str, str]) -> None:
+        self._docs = {k: Counter(_TOKEN.findall(v.lower())) for k, v in documents.items()}
+        n = len(self._docs) or 1
+        df: Counter = Counter()
+        for counts in self._docs.values():
+            df.update(counts.keys())
+        self._idf = {t: math.log((n + 1) / (c + 1)) + 1.0 for t, c in df.items()}
+
+    def _vector(self, counts: Mapping[str, int]) -> dict[str, float]:
+        vec = {t: (1 + math.log(c)) * self._idf.get(t, 1.0) for t, c in counts.items()}
+        norm = math.sqrt(sum(v * v for v in vec.values())) or 1.0
+        return {t: v / norm for t, v in vec.items()}
+
+    def rank(self, query: str, k: int) -> list[str]:
+        q = self._vector(Counter(_TOKEN.findall(query.lower())))
+        scored = []
+        for doc_id, counts in self._docs.items():
+            d = self._vector(counts)
+            score = sum(w * d.get(t, 0.0) for t, w in q.items())
+            if score > 0:
+                scored.append((doc_id, score))
+        scored.sort(key=lambda pair: (-pair[1], pair[0]))
+        return [doc_id for doc_id, _ in scored[:k]]

authorized_recall-0.1.0/src/authorized_recall.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: authorized-recall
+Version: 0.1.0
+Summary: Authorized Recall@K — retrieval quality measured over the subset a principal is permitted to use
+Author: Alexander Chernov
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/agentic-datasets/reference
+Project-URL: Documentation, https://agenticdatasets.org/reference/
+Project-URL: Source, https://github.com/agentic-datasets/reference/tree/main/packages/authorized-recall
+Keywords: information retrieval,evaluation metric,authorization,access control,multi-tenant,RAG,ABAC,RBAC
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Authorized Recall@K
+
+**Retrieval quality measured over the subset a principal may actually use.**
+
+This package has no dependency on the rest of the repository. The metric takes
+a predicate, not a `Principal`, so a system using RBAC, ABAC, row-level
+security or per-tenant vector namespaces can adopt the measurement without
+adopting anything else here.
+
+```bash
+pip install authorized-recall
+python -m authorized_recall           # or: authorized-recall
+```
+
+---
+
+## Why
+
+A retrieval system that surfaces a dataset the caller is not permitted to use
+has not helped them. They cannot act on it; the only thing that changed is that
+they now know it exists. Standard Recall@K scores that as a success, and it has
+also spent one of the K slots doing it.
+
+In the corpus measured here, **68.8% of what retrieval returns is unusable to
+the principal who asked**, and Recall@K cannot see it.
+
+## Definition
+
+Let
+
+- $D$ — the corpus,
+- $q$ — a query, with relevant set $R(q) \subseteq D$,
+- $p$ — a principal, with authorization predicate $A_p : D \to \{0,1\}$,
+- $L_K(q,p)$ — the ordered list of at most $K$ items the system returns.
+
+The **authorized relevant set** is
+
+$$R_A(q,p) = \{\, d \in R(q) : A_p(d) = 1 \,\}$$
+
+and
+
+$$\mathrm{ARecall}@K(q,p) = \frac{|R_A(q,p) \cap L_K(q,p)|}{|R_A(q,p)|},
+\qquad \mathrm{ARecall}@K \triangleq 1 \ \text{ when } R_A = \emptyset .$$
+
+Compare
+
+$$\mathrm{Recall}@K(q) = \frac{|R(q) \cap L_K|}{|R(q)|} .$$
+
+**When $A_p \equiv 1$, $\mathrm{ARecall}@K = \mathrm{Recall}@K$.** The metric is
+a strict generalisation, not a different measurement.
+
+### Two conventions, stated because they change the mean
+
+1. $R_A = \emptyset \Rightarrow \mathrm{ARecall}@K = 1$. The system cannot be
+   faulted for failing to surface what it must not surface. Over a population
+   containing such pairs this inflates the mean, so report the restricted mean
+   — over pairs with $R_A \neq \emptyset$ — alongside it. The experiment here
+   prints both.
+2. Retrieved-but-unauthorized items are neither credited nor penalised inside
+   ARecall. They are a separate quantity:
+
+$$U@K(q,p) = \frac{|\{\, d \in L_K : A_p(d) = 0 \,\}|}{K}$$
+
+## Where the filter sits
+
+ARecall is computed over the list the system **returns**, so it is sensitive to
+whether truncation happens before or after the authorization filter:
+
+$$L_K^{\text{post}} = \sigma_{A_p}\big(\mathrm{top}_K(\mathrm{rank}(D))\big)
+\qquad
+L_K^{\text{pre}} = \mathrm{top}_K\big(\sigma_{A_p}(\mathrm{rank}(D))\big)$$
+
+**Claim.** $L_K^{\text{post}} \subseteq L_K^{\text{pre}}$ for every ranking,
+$K$ and $A_p$, hence
+
+$$\Delta@K = \mathrm{ARecall}^{\text{pre}}@K - \mathrm{ARecall}^{\text{post}}@K \;\geq\; 0 .$$
+
+*Proof.* Filtering preserves relative order. An item in $L_K^{\text{post}}$ is
+authorized and appears within the first $K$ positions of the ranking, so at
+most $K-1$ items precede it, so at most $K-1$ *authorized* items precede it,
+so it appears within the first $K$ authorized items — which is
+$L_K^{\text{pre}}$. ∎
+
+The gap is therefore non-negative by construction rather than by luck of the
+corpus. What the corpus determines is its *size*.
+
+## Measured
+
+40 synthetic datasets over 8 domains, 24 queries, 4 authorization profiles,
+96 query-principal pairs. Relevance by construction: a dataset is relevant to a
+query when it is in the query's domain. Retrieval is TF-IDF cosine.
+
+```
+  K   Recall  ARecall  ARecall    gap  unusable
+                 post      pre         in top-K
+  1    0.200    0.750    0.750 +0.000     68.8%
+  3    0.483    0.835    0.863 +0.027     68.8%
+  5    0.867    0.954    0.988 +0.033     68.5%
+ 10    1.000    1.000    1.000 +0.000     39.1%
+```
+
+Restricted to the 30 pairs with $R_A \neq \emptyset$:
+
+```
+  K  ARecall post  ARecall pre     gap
+  1         0.200        0.200  +0.000
+  3         0.473        0.560  +0.087
+  5         0.853        0.960  +0.107
+ 10         1.000        1.000  +0.000
+```
+
+**At K=5, moving the filter ahead of truncation takes ARecall@5 from 0.853 to
+0.960 (+0.107). Recall@5 stays at 0.867 and cannot see the difference.**
+
+## What this does and does not establish
+
+The absolute values belong to this corpus: relevance is by construction, the
+retriever is TF-IDF, and MRR is 1.000, so the retrieval task is easy. A harder
+corpus or a better retriever moves all three columns.
+
+The *gap* is what the metric was defined to isolate, and the claim above is
+that it is a property of filter placement rather than of retrieval quality. The
+proof makes its sign certain; the experiment gives its size in one setting.
+
+Applying it to a real corpus with real authorization data is the obvious next
+measurement, and this package is separable precisely so that someone else can
+do it.

authorized_recall-0.1.0/src/authorized_recall.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/authorized_recall/__init__.py
+src/authorized_recall/__main__.py
+src/authorized_recall/corpus.py
+src/authorized_recall/experiment.py
+src/authorized_recall/metric.py
+src/authorized_recall/retrieval.py
+src/authorized_recall.egg-info/PKG-INFO
+src/authorized_recall.egg-info/SOURCES.txt
+src/authorized_recall.egg-info/dependency_links.txt
+src/authorized_recall.egg-info/entry_points.txt
+src/authorized_recall.egg-info/requires.txt
+src/authorized_recall.egg-info/top_level.txt

authorized_recall-0.1.0/src/authorized_recall.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

authorized_recall-0.1.0/src/authorized_recall.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+authorized-recall = authorized_recall.experiment:main

authorized_recall-0.1.0/src/authorized_recall.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8

authorized_recall-0.1.0/src/authorized_recall.egg-info/top_level.txt

@@ -0,0 +1 @@
+authorized_recall