proactive-gate 0.2.1 → 0.2.2

package/README.md

@@ -100,12 +100,37 @@ something returned false".
 | 5 | `snooze()` | `user.snoozedUntil` is in the future | global pause |
 | 6 | `mute()` | `candidate.type` is in `user.mutedTypes` | per-type mute |
 | 7 | `intensity()` | priority is below the user's intensity floor | low hears only high, normal hears normal and up, high hears everything |
-| 8 | `quietHours({ priorityFloor })` | inside the user's local quiet window | IANA time zone, window may cross midnight, bypassed at or above the floor |
+| 8 | `quietHours({ priorityFloor })` | inside the user's local quiet window | IANA time zone, window may cross midnight, bypassed at or above the floor; one window every day or [a schedule per day](#quiet-hours-that-differ-by-day) |
 | 9 | `trustRamp({ days, minPriority })` | user is newer than `days` and priority is below the floor | the system is least calibrated exactly when the user is least forgiving |
 | 10 | `dismissalCooldown({ dismissals, withinDays, silenceDays })` | the user dismissed that type `dismissals` times in the window | fed by `gate.record(user, candidate, "dismissed")`; every further dismissal restarts the silence |
 | 11 | `adaptiveTiming({ nextGoodMoment, surfacesFor })` | never | non-rejecting: moves `deliverAt` or narrows surfaces; a check marked `nonRejecting` cannot reject even if it tries |
 | 12 | `dailyBudget({ limit, bypassPriority })` | the user's local-day counter is at the limit | `evaluate` reads, `commit` increments atomically and can still refuse |
 
+### Quiet hours that differ by day
+
+A working week is not Monday to Friday everywhere, and a holiday is not a weekday at all.
+`quietHours` takes a schedule as well as a single window:
+
+```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" } },
+}
+```
+
+A date beats a weekday beats the default, and `null` means the day has no quiet hours, which is
+how a working day is carved out of a default. A window belongs to the day it opens on, so one
+that crosses midnight silences the next morning and the reason names the day it came from.
+
+Two things this deliberately does not do. There is no bundled holiday calendar: the dates you
+observe are yours to supply, and a bundled one goes stale without anyone noticing. And one row
+cannot express more than 24 hours, so a Friday evening to Saturday evening silence is two rows,
+`fri: 18:00 to 00:00` and `sat: 00:00 to 20:00`.
+
+Passing a single window is unchanged and remains the common case; a schedule whose every day
+resolves to the same window behaves identically to that window.
+
 `weeklyBudget({ limit, bypassPriority })` is the same shape keyed on the user's local ISO
 week; `defaultChecks({ weeklyLimit })` places it just before the daily one. Budgets are
 consumed in check order at commit, so when a weekly check passes and the daily one then
@@ -472,6 +497,10 @@ preset) still refuses. Both are part of `npm run examples` and of the test suite
 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.
+
 ```python
 from proactive_gate import Gate
 gate = Gate.from_policy(policy)          # the same policy.json

package/README.tr.md

@@ -309,6 +309,10 @@ kurmak gerekmez. Her biri kapının gerekçesiyle reddeder ve onayda bütçeyi t
 pip install proactive-gate
 ```
 
+Yayınlanmamış bir durumu denemek için depodan kurulur: `pip install "proactive-gate @
+git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`. Yayınlanan sürüm yerel bir
+derlemeden token ile yüklendi; npm paketinin aksine derleme kanıtı taşımıyor.
+
 `python/` sapan bir port değil, bir kardeştir: `spec/fixtures` altındaki her senaryoyu senkron
 `Gate` ve `AsyncGate` (Redis, `redis.asyncio` üzerinden) ile geçer; mypy strict, CI'da Python
 3.11 ve 3.13. Bkz. [`python/README.md`](python/README.md).

package/dist/src/checks.d.ts

@@ -1,4 +1,4 @@
-import type { Check, CheckContext, Priority, Surface } from "./types.js";
+import type { Check, CheckContext, Priority, QuietSchedule, QuietWindow, Surface, Weekday } from "./types.js";
 export declare const DAY_SECONDS: number;
 /** Local "HH:MM" and calendar day for an instant in an IANA zone, using Intl only. */
 export declare function localClock(now: Date, timezone: string): {
@@ -7,6 +7,30 @@ export declare function localClock(now: Date, timezone: string): {
 };
 /** True when `minutes` falls inside [start, end), where the window may cross midnight. */
 export declare function inWindow(minutes: number, start: number, end: number): boolean;
+/**
+ * The weekday of a local calendar date, and the date before it.
+ *
+ * Both are pure calendar arithmetic on the "YYYY-MM-DD" that `localClock` already
+ * resolved through Intl, never arithmetic on an instant. That is what keeps zones
+ * with a 45-minute offset (Kathmandu, Chatham, Eucla) and every daylight-saving
+ * transition out of this: the offset was applied before we got here.
+ */
+export declare function weekdayOf(day: string): Weekday;
+export declare function dayBefore(day: string): string;
+/** The window in force on one local date: a date beats a weekday beats the default. */
+export declare function windowFor(quiet: QuietWindow | QuietSchedule, day: string): QuietWindow | null;
+/**
+ * Whether a local time is inside quiet hours, and which day's window says so.
+ *
+ * A window that crosses midnight belongs to the day it opens on, so a time can be
+ * quiet because of yesterday: Friday 18:00 to 00:00 silences Saturday 00:00 too.
+ * With one window every day this reduces exactly to `inWindow`, which is why the
+ * single-window form keeps behaving as it did.
+ */
+export declare function quietAt(quiet: QuietWindow | QuietSchedule, day: string, minutes: number): {
+    window: QuietWindow;
+    day: string;
+} | null;
 /** A production hard-stop that silences every producer at once. */
 export declare function killSwitch(isOn: () => boolean | Promise<boolean>): Check;
 /** Consent comes before everything, or you have evaluated preferences for someone who never agreed. */

package/dist/src/checks.js

@@ -39,6 +39,61 @@ export function inWindow(minutes, start, end) {
     return start < end ? minutes >= start && minutes < end : minutes >= start || minutes < end;
 }
 const localDay = (now, timezone) => (timezone ? localClock(now, timezone).day : now.toISOString().slice(0, 10));
+const WEEKDAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+/**
+ * The weekday of a local calendar date, and the date before it.
+ *
+ * Both are pure calendar arithmetic on the "YYYY-MM-DD" that `localClock` already
+ * resolved through Intl, never arithmetic on an instant. That is what keeps zones
+ * with a 45-minute offset (Kathmandu, Chatham, Eucla) and every daylight-saving
+ * transition out of this: the offset was applied before we got here.
+ */
+export function weekdayOf(day) {
+    const [y, m, d] = day.split("-").map(Number);
+    return WEEKDAYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()];
+}
+export function dayBefore(day) {
+    const [y, m, d] = day.split("-").map(Number);
+    return new Date(Date.UTC(y, m - 1, d - 1)).toISOString().slice(0, 10);
+}
+const isSchedule = (q) => !("start" in q);
+/** The window in force on one local date: a date beats a weekday beats the default. */
+export function windowFor(quiet, day) {
+    if (!isSchedule(quiet))
+        return quiet;
+    const byDate = quiet.dates?.[day];
+    if (byDate !== undefined)
+        return byDate;
+    const byDay = quiet.days?.[weekdayOf(day)];
+    if (byDay !== undefined)
+        return byDay;
+    return quiet.default ?? null;
+}
+/**
+ * Whether a local time is inside quiet hours, and which day's window says so.
+ *
+ * A window that crosses midnight belongs to the day it opens on, so a time can be
+ * quiet because of yesterday: Friday 18:00 to 00:00 silences Saturday 00:00 too.
+ * With one window every day this reduces exactly to `inWindow`, which is why the
+ * single-window form keeps behaving as it did.
+ */
+export function quietAt(quiet, day, minutes) {
+    const today = windowFor(quiet, day);
+    if (today) {
+        const start = parseHHMM(today.start);
+        const end = parseHHMM(today.end);
+        if (start !== end && (start < end ? minutes >= start && minutes < end : minutes >= start))
+            return { window: today, day };
+    }
+    const yesterday = windowFor(quiet, dayBefore(day));
+    if (yesterday) {
+        const start = parseHHMM(yesterday.start);
+        const end = parseHHMM(yesterday.end);
+        if (start > end && minutes < end)
+            return { window: yesterday, day: dayBefore(day) };
+    }
+    return null;
+}
 /* ------------------------------------------------------------------------ */
 /* The checks, in the order LILA runs them. Compose your own order freely.  */
 /* ------------------------------------------------------------------------ */
@@ -117,14 +172,16 @@ export function quietHours(options = {}) {
                 return pass;
             if (!user.timezone)
                 return skip("quiet hours set but no timezone on the user; cannot evaluate");
-            const { minutes } = localClock(now, user.timezone);
-            const start = parseHHMM(user.quietHours.start);
-            const end = parseHHMM(user.quietHours.end);
-            if (!inWindow(minutes, start, end))
+            const { minutes, day } = localClock(now, user.timezone);
+            const hit = quietAt(user.quietHours, day, minutes);
+            if (!hit)
                 return pass;
             if (atLeast(priority, floor))
                 return pass;
-            return reject(`quiet hours ${user.quietHours.start} to ${user.quietHours.end} ${user.timezone}; priority ${priority} is below the floor (${floor})`);
+            // Name the day the window came from: when it crossed midnight the reason is
+            // yesterday's setting, and a reader looking at today's would not find it.
+            const whose = hit.day === day ? "" : ` (${weekdayOf(hit.day)} ${hit.day})`;
+            return reject(`quiet hours ${hit.window.start} to ${hit.window.end}${whose} ${user.timezone}; priority ${priority} is below the floor (${floor})`);
         },
     };
 }

package/dist/src/types.d.ts

@@ -3,6 +3,27 @@ export type Priority = "low" | "normal" | "high" | "critical";
 export declare const PRIORITY_RANK: Record<Priority, number>;
 /** Where a delivery may land. Free-form so callers can add their own. */
 export type Surface = "feed" | "push" | "chat" | "voice" | "email" | (string & {});
+/** A quiet window in local time, "HH:MM" to "HH:MM". `start` after `end` crosses midnight. */
+export type QuietWindow = {
+    start: string;
+    end: string;
+};
+/** Weekday keys for a quiet-hours schedule, Sunday first to match `Date#getUTCDay`. */
+export type Weekday = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+/**
+ * Quiet hours that differ by day. A working week is not Monday to Friday everywhere,
+ * and a holiday is not a weekday at all, so the window is resolved per day: a calendar
+ * date first, then the weekday, then the default. `null` at any level means the day has
+ * no quiet hours.
+ *
+ * There is no bundled holiday calendar and there will not be one: the dates a caller
+ * observes are the caller's to supply, and a bundled calendar goes stale silently.
+ */
+export type QuietSchedule = {
+    default?: QuietWindow | null;
+    days?: Partial<Record<Weekday, QuietWindow | null>>;
+    dates?: Record<string, QuietWindow | null>;
+};
 /** Everything the gate knows about the person it might interrupt. */
 export interface UserState {
     id: string;
@@ -20,11 +41,25 @@ export interface UserState {
     intensity?: "low" | "normal" | "high";
     /** IANA time zone, required for quiet hours. */
     timezone?: string;
-    /** Quiet hours in local time, "HH:MM". May cross midnight. */
-    quietHours?: {
-        start: string;
-        end: string;
-    } | null;
+    /**
+     * Quiet hours in local time, "HH:MM". May cross midnight.
+     *
+     * One window applies every day. A schedule gives a window per weekday, and per
+     * calendar date for the days a weekday cannot express, such as a public holiday:
+     *
+     * ```ts
+     * quietHours: {
+     *   default: { start: "22:00", end: "08:00" },
+     *   days: { fri: { start: "18:00", end: "00:00" }, sat: { start: "00:00", end: "20:00" } },
+     *   dates: { "2026-12-25": { start: "00:00", end: "23:59" } },
+     * }
+     * ```
+     *
+     * `null` for a weekday or a date means no quiet hours that day, which is how you
+     * carve a working day out of a default. A date beats a weekday, a weekday beats
+     * the default. Dates are the user's local calendar dates, "YYYY-MM-DD".
+     */
+    quietHours?: QuietWindow | QuietSchedule | null;
     /** When the user joined. Drives the trust ramp. */
     createdAt?: Date | string;
     /** Surfaces the user allows, in preference order. Defaults to the candidate's surfaces. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proactive-gate",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",