proactive-gate 0.2.4 → 0.2.5

package/README.md

@@ -9,6 +9,7 @@ English | [Türkçe](README.tr.md)
   <img src="https://img.shields.io/bundlephobia/minzip/proactive-gate?style=flat-square&color=111111" alt="minzipped size">
   <img src="https://img.shields.io/github/stars/Bubblegunn/proactive-gate?style=flat-square&color=111111" alt="stars">
   <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT">
+  <a href="https://doi.org/10.5281/zenodo.22393512"><img src="https://img.shields.io/badge/DOI-10.5281%2Fzenodo.22393512-111111?style=flat-square" alt="DOI"></a>
 </p>
 
 Decide whether a proactive AI agent may reach a user right now, and log why not.
@@ -138,21 +139,23 @@ consumed in check order at commit, so when a weekly check passes and the daily o
 refuses, that weekly unit is spent without a delivery. It only happens when two commits
 race after a shared evaluate.
 
-### Two limits you should know before you adopt this
+### One limit you should know before you adopt this
 
-Neither is a bug, and both are pinned by tests so a future change has to be deliberate.
+It is not a bug, and it is pinned by tests so a future change has to be deliberate.
 
-**The week is the ISO week, so the weekly budget refills on Monday.** Where the working
-week runs Sunday to Thursday, that refill lands one day in: a user who spends the budget on
-Sunday has it back on Monday, with four working days still to run. Changing the key would
-move every counter already in your store, so it is documented rather than quietly altered.
-Pass your own budget check keyed how you like if the ISO week is wrong for your users.
-
-**Quiet hours are a single window, the same on every day of the week.** A user carries one
-`start` and one `end`, so a Friday window, a Shabbat window or a public holiday cannot be
-expressed. The day of the week is never read. If you need one, write a check: it is an
-object with an `id` and a `run`, it composes in the order you choose, and the trace will
-show it firing beside the built-in ones.
+**The week is the ISO week, so the weekly budget refills on Monday.** Monday is not where
+the week starts for most people: of the twenty most populous countries, CLDR gives Monday
+to seven, Sunday to eleven and Saturday to two, which you can read yourself with
+`new Intl.Locale("und-EG").getWeekInfo().firstDay`. Where the working week runs Sunday to
+Thursday, an ISO refill lands one day in: a user who spends the budget on Sunday has it back
+on Monday with four working days still to run. The key is ISO anyway, for two reasons. A
+counter already in your store is keyed by it, and moving the key silently resets every user
+mid-week. And the day the counter turns over is not the day the user is protected on: quiet
+hours already read the user's own weekday, including a Friday or a Shabbat window, and they
+are what decides when a notification is allowed. The budget only decides how many. If the ISO
+week is wrong for your users, pass your own budget check keyed how you like; it is an object
+with an `id` and a `run`, it composes in the order you choose, and the trace will show it
+firing beside the built-in ones.
 
 Order is a design decision and it should be visible. Consent has to come before
 everything. Quiet hours have to come before the budget, or a rejected candidate
@@ -550,8 +553,10 @@ pip install proactive-gate
 ```
 
 To run an unreleased state, install from the repository instead: `pip install "proactive-gate @
-git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. The published release was
-uploaded from a local build with a token, so unlike the npm package it carries no build provenance.
+git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. The Python package is published by
+the same workflow as the npm one, so it carries PyPI publish attestations naming the repository
+and the workflow that built each file. Releases before 0.2.2 were uploaded from a local build with
+a token and carry none.
 
 ```python
 from proactive_gate import Gate
@@ -721,6 +726,18 @@ before. [@aaqib-hafeez-khan-in](https://github.com/aaqib-hafeez-khan-in) wrote `
 ([#9](https://github.com/Bubblegunn/proactive-gate/pull/9)). Both shipped in 0.1.2 and are in
 every release since, including the one you install today.
 
+## Cite this
+
+Every release is archived on Zenodo with a DOI, so a paper or a report can point at the
+exact code it ran.
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22393512.svg)](https://doi.org/10.5281/zenodo.22393512)
+
+That is the **concept** DOI: it always resolves to the newest version. To cite the exact
+version you ran, open that page, pick the version in the sidebar, and use the DOI shown
+there. `CITATION.cff` in this repository carries the same identifier, so GitHub's "Cite this
+repository" button produces correct BibTeX and APA without any copying by hand.
+
 ## Development
 
 ```

package/README.tr.md

@@ -81,12 +81,37 @@ olurdu.
 | 5 | `snooze()` | `user.snoozedUntil` gelecekteyse | genel duraklatma |
 | 6 | `mute()` | `candidate.type`, `user.mutedTypes` içindeyse | tür bazlı susturma |
 | 7 | `intensity()` | öncelik, kullanıcının yoğunluk tabanının altındaysa | low yalnızca high duyar, normal normal ve üstünü, high her şeyi |
-| 8 | `quietHours({ priorityFloor })` | kullanıcının yerel sessiz penceresi içindeyse | IANA saat dilimi, pencere gece yarısını geçebilir, taban ve üstünde atlanır |
+| 8 | `quietHours({ priorityFloor })` | kullanıcının yerel sessiz penceresi içindeyse | IANA saat dilimi, pencere gece yarısını geçebilir, taban ve üstünde atlanır; her gün tek pencere ya da [güne göre bir çizelge](#güne-göre-değişen-sessiz-saatler) |
 | 9 | `trustRamp({ days, minPriority })` | kullanıcı `days` günden yeniyse ve öncelik tabanın altındaysa | sistem, kullanıcı en az bağışlayıcıyken en az kalibredir |
 | 10 | `dismissalCooldown({ dismissals, withinDays, silenceDays })` | kullanıcı o türü pencere içinde `dismissals` kez reddettiyse | `gate.record(user, candidate, "dismissed")` ile beslenir; her yeni ret sessizliği yeniden başlatır |
 | 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | asla | reddetmez: `deliverAt` değerini taşır ya da yüzeyleri daraltır; `nonRejecting` işaretli bir kontrol istese de reddedemez |
 | 12 | `dailyBudget({ limit, bypassPriority })` | kullanıcının yerel gün sayacı sınırdaysa | `evaluate` okur, `commit` atomik artırır ve yine de reddedebilir |
 
+### Güne göre değişen sessiz saatler
+
+Çalışma haftası her yerde pazartesiden cumaya değildir ve tatil günü zaten hafta içi
+değildir. `quietHours` tek bir pencerenin yanında bir çizelge de alır:
+
+```ts
+quietHours: {
+  default: { start: "22:00", end: "08:00" },
+  days: { fri: { start: "00:00", end: "23:59" }, sat: { start: "00:00", end: "23:59" }, sun: null },
+  dates: { "2026-12-25": { start: "00:00", end: "23:59" } },
+}
+```
+
+Tarih haftanın gününü, o da varsayılanı yener; `null` o günün sessiz saati yok demektir ve
+varsayılanın içinden bir iş günü böyle oyulur. Bir pencere açıldığı güne aittir, yani gece
+yarısını geçen bir pencere ertesi sabahı susturur ve gerekçe hangi günden geldiğini söyler.
+
+Bunun bilerek yapmadığı iki şey var. Gömülü bir tatil takvimi yok: hangi tarihleri
+tuttuğunuz size aittir, gömülü olan ise kimse fark etmeden bayatlar. Ve tek bir satır 24
+saatten fazlasını anlatamaz, yani cuma akşamından cumartesi akşamına uzanan bir sessizlik
+iki satırdır: `fri: 18:00 to 00:00` ve `sat: 00:00 to 20:00`.
+
+Tek pencere geçmek eskisi gibi çalışır ve yaygın durum olmayı sürdürür; her günü aynı
+pencereye çıkan bir çizelge, o pencereyle birebir aynı davranır.
+
 Sıra bir tasarım kararıdır ve görünür olmalıdır. Rıza her şeyden önce gelmelidir. Sessiz
 saatler bütçeden önce gelmelidir, yoksa reddedilen bir aday hiç yapmadığı bir teslimi
 tüketir. İstediğiniz gibi yeniden sıralayın; iz ne yaptığınızı gösterecektir.
@@ -227,22 +252,24 @@ işyerinde sürekli ulaşılabilir olmaları beklendiği için katılmayı redde
 seçmediği bir sessizliğin bir bedeli var ve o bedel bu kütüphanenin yazdığı hiçbir izde
 görünmüyor.
 
-## Benimsemeden önce bilmeniz gereken iki sınır
-
-İkisi de hata değil ve ikisi de testle sabitlendi, böylece ileride değişecekse bilerek değişir.
-
-**Hafta, ISO haftasıdır; haftalık bütçe pazartesi yenilenir.** Çalışma haftası pazardan
-perşembeye uzanan yerlerde bu yenilenme haftanın birinci gününe denk gelir: pazar günü
-bütçesini harcayan bir kullanıcı pazartesi sabahı bütçesini geri alır ve önünde hâlâ dört
-iş günü vardır. Anahtarı değiştirmek deponuzdaki bütün sayaçları kaydıracağı için bunu
-sessizce değiştirmek yerine yazıyoruz. ISO haftası sizin kullanıcılarınız için yanlışsa
-kendi bütçe kontrolünüzü istediğiniz anahtarla yazabilirsiniz.
-
-**Sessiz saatler tek bir penceredir ve haftanın her günü aynıdır.** Kullanıcıda tek bir
-`start` ve tek bir `end` vardır; cuma penceresi, Şabat penceresi veya resmî tatil
-tanımlanamaz. Haftanın günü hiç okunmaz. Böyle bir kurala ihtiyacınız varsa kendi
-kontrolünüzü yazın: `id` ve `run` taşıyan bir nesnedir, istediğiniz sırada dizilir ve izde
-yerleşik kontrollerin yanında görünür.
+## Benimsemeden önce bilmeniz gereken bir sınır
+
+Hata değil ve testle sabitlendi, böylece ileride değişecekse bilerek değişir.
+
+**Hafta, ISO haftasıdır; haftalık bütçe pazartesi yenilenir.** Pazartesi, çoğu insan için
+haftanın başladığı gün değildir: en kalabalık yirmi ülkeden CLDR'ye göre yedisinde
+pazartesi, on birinde pazar, ikisinde cumartesi başlar; bunu kendiniz
+`new Intl.Locale("und-EG").getWeekInfo().firstDay` ile okuyabilirsiniz. Çalışma haftası
+pazardan perşembeye uzanan yerlerde ISO yenilenmesi haftanın birinci gününe denk gelir:
+pazar günü bütçesini harcayan bir kullanıcı pazartesi sabahı bütçesini geri alır ve önünde
+hâlâ dört iş günü vardır. Anahtar yine de ISO, iki nedenle. Deponuzdaki sayaç bu anahtarla
+tutuluyor ve anahtarı taşımak her kullanıcıyı haftanın ortasında sessizce sıfırlar. Ayrıca
+sayacın döndüğü gün, kullanıcının korunduğu gün değildir: sessiz saatler kullanıcının kendi
+haftalık gününü zaten okuyor, cuma ya da Şabat penceresi dahil, ve bildirimin ne zaman
+verilebileceğine onlar karar veriyor. Bütçe yalnız kaç tane olacağına karar verir. ISO
+haftası sizin kullanıcılarınız için yanlışsa kendi bütçe kontrolünüzü istediğiniz anahtarla
+yazın: `id` ve `run` taşıyan bir nesnedir, istediğiniz sırada dizilir ve izde yerleşik
+kontrollerin yanında görünür.
 
 ## Hazır paketler: platform kotaları ve yasal sınırlar, kaynaklarıyla
 
@@ -463,6 +490,18 @@ başına bir anahtar ve sessiz saati aşan bir öncelik tabanı verir. Horvitz'i
 çalışmaları iki isteğe bağlı kontrolü sağladı. Bu paket o fikirleri izli tek bir listeye
 koyar ve onların dışarıda bıraktığı parçayı ekler: gönderim anında tüketilen bütçe.
 
+## Atıf
+
+Her sürüm Zenodo'da bir DOI ile arşivleniyor, böylece bir makale ya da rapor tam olarak
+çalıştırdığı koda işaret edebiliyor.
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22393512.svg)](https://doi.org/10.5281/zenodo.22393512)
+
+Bu **kavram** DOI'si: her zaman en yeni sürüme çözümlenir. Çalıştırdığınız sürümün kendisini
+atıflamak için o sayfayı açıp yan çubuktan sürümü seçin ve orada yazan DOI'yi kullanın.
+Depodaki `CITATION.cff` aynı tanımlayıcıyı taşıyor, bu yüzden GitHub'ın "Cite this repository"
+düğmesi elle kopyalama olmadan doğru BibTeX ve APA üretiyor.
+
 ## Geliştirme
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Decide whether a proactive AI agent may reach a user right now, and log why not. Ordered checks as code or JSON, a conformance spec, presets for platform and legal limits, adapters for AI SDK, Mastra, LangChain and OpenAI Agents, and a Python sibling.",
   "type": "module",
   "main": "./dist/src/index.js",