librus-python-api 1.0.0rc1__tar.gz → 1.0.1__tar.gz

{librus_python_api-1.0.0rc1 → librus_python_api-1.0.1}/API.md

@@ -5,6 +5,36 @@ Core public values are exported from `librus_python_api`; exceptions live in
 `librus_python_api.persistence`. Results are frozen dataclasses. Their reprs omit
 personal fields. Serializing them for MCP or anything else is the consumer's job.
 
+## Compatibility policy
+
+Version 1.0 freezes the documented public library contracts: root exports and
+explicit optional modules described here, typed account/source ownership, bounded
+traffic/resources, explicit effect consent and fail-closed error semantics.
+Private names, parser internals, SQLite SQL layout and encoded archive internals
+are not consumer integration APIs. Use the supported typed persistence methods.
+
+Within 1.x, patch releases repair documented behavior and security issues; minor
+releases add supported capabilities. Removal/renaming of public methods or
+required fields, incompatible argument/return types, or changes to established
+canonical IDs require a major release. Dataclass fields may be added with defaults;
+construct by keyword and serialize deliberately, not by assuming a fixed repr.
+Undocumented upstream layouts are not compatibility promises: they may fail with
+typed PARSE/UNSUPPORTED_CAPABILITY rather than produce guessed partial output.
+Security fixes can tighten validation of previously accepted invalid/unsafe input.
+
+Persisted supported records are validated without silent reset or reinterpretation.
+An incompatible future format requires explicit migration and preserved originals.
+Upgrades can introduce records older versions cannot read; keep original files and
+archives for consumer-owned rollback, never clear UNKNOWN sends or acknowledge
+notifications merely to make a downgrade work. The stable application context key
+remains required. The neutral bootstrap does not automatically migrate old consumer
+files or reconstruct missing identity/observation provenance.
+
+Library stability is not a Librus availability guarantee or completed MCP migration.
+The documented default-off features, unobserved layouts and pending live evidence
+stay limited as stated. Consumers qualify their own DTO/stdio contracts, mapped
+state migration/rollback and exact installed dependency before production cutover.
+
 ## Optional local attachment files
 
 ```python
@@ -25,6 +55,14 @@ content type. It neither selects the destination nor opens message content.
 See [the file contract](contracts/attachment-files.md) for filesystem requirements,
 bounded naming and cancellation/commit semantics.
 
+`await prepare_attachment_directory(directory: Path)` explicitly creates or
+validates an absolute caller-selected private directory whose parent exists.
+It creates mode 0700 on POSIX or a protected inheritable private ACL on local
+Windows NTFS. Unsafe existing directories reject, never have their permissions
+silently changed. It performs no HTTP and joins disk work on cancellation, which
+may leave a complete empty directory. `publish_attachment` still requires an
+existing directory; it never creates a destination implicitly.
+
 ## Service and accounts
 
 ```python
@@ -469,8 +507,10 @@ context identifiers are store-local HMAC-SHA256 pseudonyms, not the public
 `client.context.identifier` application-keyed pseudonym. `store.context_identifier(client.context.identifier)`
 returns that pseudonym only on an open store. Core clients remain storage-independent.
 Version-1/2 stores reject without modification; no automatic migration/reset.
-Opening either store requires POSIX; other platforms fail with
-`UnsupportedCapabilityError` before creating files.
+Opening either store requires local POSIX filesystem safeguards or fixed local
+Windows NTFS with private protected inheritable ACLs. Network/UNC/device paths,
+non-NTFS volumes and reparse-point paths are unsupported or rejected before unsafe
+work. See [the Windows boundary](contracts/persistence.md#windows-disk-boundary-25).
 
 `await store.prune_send_history(context=client.context, identifiers=(...),
 allow_accepted=False)` returns the number of deleted rows. Use identifiers from
@@ -525,7 +565,7 @@ creates state, reads old MCP files or starts background recovery.
   tokens and neither clears uncertainty nor authorizes another send.
 - SQLite FULL synchronous transactions serialize cross-process claims. Unknown
   schema, extra triggers, corrupt data, replaced files, symlinks, non-regular
-  files and unsafe POSIX permissions fail closed, never reset/migrate state.
+  files and unsafe POSIX permissions or Windows ACLs fail closed, never reset state.
   No automatic retry, reconciliation, deletion of consumed history or polling.
 - Defaults: 8 admitted storage workers and 8 send workflows, 256 total records,
   32 unused previews, 300-second expiry and 0.1-second SQLite busy timeout.
@@ -565,7 +605,10 @@ notified again; no automatic school-year/age expiry is performed.
 
 Explicitly import `NotificationStore`, `NotificationLimits`, `NotificationWorkflow`,
 `NotificationBatch`, `NotificationItem`, `NotificationState`, `NotificationSeen`,
-`NotificationArchive` and `canonical_notification_id` from
+`NotificationArchive`, `NotificationProvenance`, `NotificationBaselineMapping`,
+`NotificationBootstrap`, `NotificationBootstrapResult`, `NotificationRecoveryStatus`,
+`NotificationPendingDelivery`, `NotificationRawCheckpointStatus` and
+`canonical_notification_id` from
 `librus_python_api.persistence`. Construction is inert; core clients remain
 independent of this optional layer.
 
@@ -585,14 +628,19 @@ async with NotificationStore(Path("/absolute/private/notification-state")) as st
 - `NotificationStore(directory: Path, *, limits=None)` opens the private separate
   `notifications.sqlite3` via `async with` or explicit `open()`/`aclose()`.
   Existing send databases remain unchanged. Select a trusted local filesystem
-  with SQLite/fsync/POSIX flock support; other platforms fail explicitly on
+  with SQLite/fsync and POSIX flock or Windows NTFS/Win32 lock support; unsupported
+  platforms fail explicitly on
   context operations. One store belongs to one event loop. Shutdown/cancellation
   joins owned work. Same-context competition fails with LIMIT, without HTTP.
-- `NotificationWorkflow(client, store).poll(*, categories, allow_consume_events=False,
+- `NotificationWorkflow(client, store, *, messages_backend=MessagingBackend.LEGACY)`
+  explicitly selects the message source. Use `MessagingBackend.MODERN` for modern
+  notifications; it does not fall back to the other mailbox on failure.
+  `.poll(*, categories, allow_consume_events=False,
   homework_window=None, checkpoint_timeout_seconds=5.0, budget=None)` accepts a
   nonempty tuple of distinct native categories. Ordinary reads precede schedule
   consumption. Homework defaults to today minus seven days through today in
-  Europe/Warsaw. Grades/attendance use LAST_LOGIN, messages use received page zero,
+  Europe/Warsaw. Grades/attendance use LAST_LOGIN. Messages use one received summary
+  page (legacy page zero or modern page one, at most ten modern summaries),
   announcements use the ordinary collection. No menu counts, message content,
   detail calls, modern fallback or arbitrary historical catch-up is performed.
 - New `AGENDA` consumption requires explicit `allow_consume_events=True` each
@@ -600,12 +648,18 @@ async with NotificationStore(Path("/absolute/private/notification-state")) as st
   Existing raw checkpoints replay locally before another consume. Malformed raw
   data remains stored and blocks another consume, even with fresh consent.
 - `NotificationBatch(receipt, context, first_run, categories, items,
-  has_more_schedule)` is a durably staged batch. Each `NotificationItem` carries
-  category, canonical identifier, native typed value, identity and observation.
+  has_more_schedule, messages_backend=MessagingBackend.LEGACY)` is a durably staged
+  batch. Modern message items contain `ModernMessageSummary`, not message bodies.
+  Each `NotificationItem` carries
+  category, canonical identifier, native typed value and provenance. OBSERVED
+  items have identity and observation; imported historical agenda items have
+  neither. Check `item.provenance` before using authentication metadata.
   First run diffs against empty IDs and ends only at acknowledgement. Requested
   categories alone update seen state. Until acknowledgement, polling the exact
   same category tuple returns that batch without authentication/HTTP. A different
-  tuple fails explicitly, not silently discarding the prior delivery.
+  tuple or message backend fails explicitly, not silently discarding the prior
+  delivery. Backend changes after acknowledgement preserve both seen namespaces;
+  the same numeric ID in two backends is not the same notification.
 - `await workflow.acknowledge(receipt)` (or
   `await store.acknowledge(receipt, context=client.context)`) atomically saves seen
   IDs, advances the schedule cursor and cleans completed raw/delivery rows.
@@ -624,7 +678,34 @@ async with NotificationStore(Path("/absolute/private/notification-state")) as st
   at 64 MiB and global staged delivery/candidate state at 16 MiB. Bounds fail closed
   without silently evicting history. A retained raw envelope can be recovered with
   explicit supported larger limits; oversized single events are never skipped.
-- `await store.export_archive(context=...)` returns a version-1 neutral archive
+- `await store.recovery_status(context=client.context)` returns a compact
+  `NotificationRecoveryStatus(context, initialized, last_acknowledged_receipt,
+  pending, raw, uncertain_consume)` snapshot without HTTP or registration of a
+  missing context. `pending` is `NotificationPendingDelivery(receipt, categories,
+  messages_backend, first_run, item_count, has_more_schedule)` or None. `raw` is
+  `NotificationRawCheckpointStatus(identifier, cursor, total, wire_bytes)` or None;
+  total can be unknown until parsing. Cursor is acknowledged progress only.
+  These are independent facts: ordinary pending delivery can coexist with retained
+  raw or uncertainty. `has_pending_work` includes all three, not just delivery.
+  A conservative marker can also belong to an in-flight poll; it is not proof
+  that the owner has finished or that another consume is safe. Resolution still
+  requires exclusive context ownership and explicit acceptance of possible loss.
+  Status exposes no event bodies or seen-ID lists and never advances recovery,
+  acknowledges a receipt, clears ambiguity, prunes or authenticates.
+- `await store.pending_batch(context=client.context)` returns the original staged
+  `NotificationBatch` or None, without category/backend arguments or HTTP. It
+  performs no raw parsing/staging: None can coexist with raw or uncertain work;
+  inspect status before deciding no recovery is needed. Retrieval remains bounded
+  by the existing batch limits and repeats unchanged until acknowledgement.
+  Raw-only recovery still requires an explicit AGENDA poll to decode locally;
+  uncertainty still requires the separate loss-consenting resolution operation.
+  Unknown valid contexts return an empty status/None and do not consume capacity.
+  Invalid contexts, malformed persisted records and aliases inconsistent with
+  retained metadata reject; no foreign delivery is returned. Use the service-owned
+  account context, not fabricated values. Status and batch lookup each read an
+  atomic snapshot, but a competing acknowledgement between the two can make an
+  earlier status stale. Use the retrieved batch receipt, never reconstruct one.
+- `await store.export_archive(context=...)` returns a version-3 neutral archive
   containing exact context, seen IDs, receipt, raw bytes/progress, pending delivery
   and uncertainty. `await store.import_archive(archive)` is empty-target-only and
   validates the complete import transaction before commit. Unknown versions,
@@ -637,7 +718,12 @@ async with NotificationStore(Path("/absolute/private/notification-state")) as st
   including possible pre-dispatch failure; it never expires or authorizes retry.
   Clearing it accepts possible lost upstream events, not proof of no consumption.
 
-`canonical_notification_id(category, value)` exposes version-1 native identities.
+`canonical_notification_id(category, value)` preserves version-1 legacy identities
+and uses a separate version-2 modern-message domain including backend, folder and
+message ID. Existing format-3 pending batches without `messages_backend` are read
+as legacy. New pending batches are not guaranteed readable by older libraries;
+keep original databases/archives for consumer-owned rollback and do not replace
+them with new exports. No SQLite schema or existing seen-ID rewrite is performed.
 Schedule hashes cover date_added/type/data; stable native IDs identify ordinary
 records where available, otherwise complete visible typed content. Stable-ID
 updates do not automatically re-notify. MCP `schedule`/legacy IDs need a separately
@@ -645,6 +731,61 @@ qualified explicit mapping to `agenda`/native IDs. See
 [contracts/persistence.md](contracts/persistence.md) for compatibility and loss
 windows. No live qualification or MCP migration is implied by offline recovery.
 
+### Offline external baseline bootstrap
+
+`await store.bootstrap(plan, *, context=client.context)` accepts a typed
+`NotificationBootstrap(context, mappings, pending_events)`. It performs no HTTP.
+The caller reads its own old files, establishes native canonical IDs and maps
+each old baseline ID with `NotificationBaselineMapping(category,
+source_identifier, native_identifier)`. Source IDs are opaque nonempty strings
+up to 256 characters; native IDs are lowercase 64-character SHA256 values.
+Use `canonical_notification_id` with independently established native records,
+not a hash of an incompatible old identifier. Numeric message IDs require their
+original backend and folder. Content-derived native IDs cannot be reconstructed
+from a legacy opaque ID alone.
+
+An unmappable ID must be submitted with `native_identifier=None`. The result has
+`imported=False`, `unmapped` containing those exact mappings and `pending=None`;
+no context, state or pending work is written. A malformed category, ID, mapping
+collision or context mismatch instead raises INVALID_INPUT. Never discard the
+unmapped report and silently poll a fresh baseline. Resolve mappings offline or
+stop migration with the originals intact.
+
+Successful import is empty-target-context only and non-overwriting. It initializes
+the mapped baseline immediately, even when the explicitly supplied mapping tuple
+is empty. Pending historical events are typed `RecentScheduleEvent` values with
+the original three strings unchanged; no raw page, identity, observation timestamp
+or session generation is invented. They form a single staged AGENDA batch with
+`first_run=False`, `has_more_schedule=False` and items marked
+`NotificationProvenance.IMPORTED_HISTORY` with `identity=None`, `observation=None`.
+Observed native items remain marked OBSERVED and require both metadata values.
+
+Mappings, seen IDs, pending count/text and encoded batch/state bytes are bounded
+by `NotificationLimits` and the native field limits. All pending events must fit
+one batch; oversized inputs fail with LIMIT, never partial import. Duplicate
+pending events or an event already included in the mapped seen baseline reject
+explicitly. Context registration, baseline and delivery commit in one SQLite
+transaction under cross-process exclusion. Repeat attempts reject and cannot
+overwrite the prior import, whether its pending batch is acknowledged or not.
+
+`NotificationBootstrapResult(imported, unmapped, pending)` returns the successful
+staged batch and receipt. After a lost response or restart, discover it with
+`store.recovery_status(context=...)` and `store.pending_batch(context=...)`, or
+replay it through
+`NotificationWorkflow(client, store).poll(categories=(NotificationCategory.AGENDA,))`
+without consume consent or network, then acknowledge its receipt normally.
+`store.state(context=...)` exposes the mapped baseline; `export_archive` and
+`import_archive` round-trip both historical and native pending work. Native
+archives are still format 3; old records without `provenance` mean OBSERVED.
+Older library versions cannot read the new historical representation.
+
+For consumer-owned rollback, retain original source files and the mapping plan,
+plus a native archive before cutover. Public replay returns the historical event
+strings and receipt; public state returns mapped seen IDs. Native IDs are one-way
+hashes, source identifiers are not persisted, and missing authentication metadata
+cannot be recovered. Therefore a generic reverse migration to a legacy store is
+not promised. Do not replace original files with this store or fabricate metadata
+to make an old importer accept new state.
 ## Message content
 
 `message_content(reference, *, allow_mark_read=False)` returns

{librus_python_api-1.0.0rc1 → librus_python_api-1.0.1}/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 1.0.1 (2026-10-06) - Bounded subject frequency and reliability fixes
+
+Compatible patch release. The public library API is unchanged.
+
+- Resolve subject-frequency lesson and subject names from the gateway `Lessons`
+  and `Subjects` collections, read once per login session and cached for the
+  existing one-hour TTL. A cold call now costs three requests regardless of how
+  many lessons and subjects a student has. Before, it cost one request per unique
+  lesson plus one per subject, which exceeded the default 32-request operation
+  budget near 15 subjects and failed with `LIMIT`. References missing from a
+  collection keep the strict per-reference routes. An unavailable, denied,
+  oversized or malformed collection falls back to them; deadlines, budgets and
+  cancellation still propagate.
+- Report a published attachment as published when removing the private temporary
+  name fails after the atomic link commit, instead of raising `STORAGE` for a
+  complete file. The inert temporary file may remain.
+- Wait up to one second, not 100 ms, for another process's SQLite write lock in
+  ordinary store operations. Several local processes commonly share one store;
+  final saves after upstream side effects keep their five-second wait.
+
+## 1.0.0 (2026-10-05) - Stable native library API
+
+Freeze the documented library API and compatibility policy for consumers moving
+to native contracts. This is a library release, not proof of completed MCP 2.0
+cutover or universal live-school compatibility. Existing school/layout limitations
+and separately authorized live checks remain explicit. No live requests or
+production-state migration occur during release qualification.
+
+- Require sealed Windows disk qualification in addition to Linux/macOS release
+  checks, on Python 3.13/3.14 with locked and newest permitted dependencies.
+- Preserve explicit account keys, format-3 state and conservative UNKNOWN sending
+  history. No automatic old-store import, silent notification reset or rollback.
+
+- Support optional Windows disk workflows on fixed local NTFS: private protected
+  inheritable ACLs, pinned directory/ancestor handles, cross-process notification
+  locks and complete non-overwriting attachment publication by handle. Add explicit
+  private attachment-directory preparation and Windows-only pywin32/tzdata runtime
+  dependencies. Reject network namespaces, unsafe ACLs and reparse-point paths.
+
+- Add compact, account-bound offline notification recovery status and pending-batch
+  lookup. Discover original categories/backend/receipt, retained raw progress and
+  uncertain consumption without remembered selections or implicit acknowledgement.
+
+- Add a neutral offline notification bootstrap API for explicitly mapped baseline
+  IDs and consumed historical events. Report unmapped IDs without writes; atomically
+  stage bounded pending history with explicit missing provenance. Preserve restart,
+  archive round-trip and acknowledgement without fabricating native metadata.
+
+- Add explicit legacy/modern mailbox selection to durable notification workflows.
+  Modern summaries use their own canonical ID domain; pending batches retain their
+  original source across restart and archive import. Existing legacy IDs and
+  format-3 state remain readable without reset or rewriting seen history.
+
 ## 1.0.0rc1 (2026-10-05) - Library-only release candidate
 
 First candidate prepared for PyPI Trusted Publishing. The supported library API

{librus_python_api-1.0.0rc1 → librus_python_api-1.0.1}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.5
 Name: librus-python-api
-Version: 1.0.0rc1
+Version: 1.0.1
 Summary: Independent bounded async Librus Synergia client
 Project-URL: Repository, https://github.com/krzysztofbury/librus-python-api
 Project-URL: Issues, https://github.com/krzysztofbury/librus-python-api/issues
 License-Expression: MIT
 License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
@@ -18,6 +19,8 @@ Requires-Python: >=3.13
 Requires-Dist: aiohttp<4,>=3.14.2
 Requires-Dist: lxml<7,>=6.1
 Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: pywin32<400,>=312; sys_platform == 'win32'
+Requires-Dist: tzdata>=2026.5; sys_platform == 'win32'
 Requires-Dist: yarl<2,>=1.20
 Description-Content-Type: text/markdown
 
@@ -31,25 +34,28 @@ Use it in personal scripts, notification services or application backends. One
 service can manage multiple logins while keeping their sessions and data separate.
 It is not an official Librus product.
 
-**Requirements:** Python 3.13 or newer. Linux and macOS are tested in CI.
-Persistence and saving attachments require POSIX filesystem features, such as
-those on Linux or macOS; Windows disk workflows are unsupported.
+**Requirements:** Python 3.13 or newer. Disk workflows require a trusted local
+POSIX filesystem on Linux/macOS, or a fixed local NTFS volume on Windows with
+private ACLs. Windows installations include `pywin32` and `tzdata` automatically.
+Network paths, reparse-point paths and unsafe storage permissions fail closed.
+See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
 
-**Status:** `1.0.0rc1`, a library-only beta prerelease, not stable 1.0 or an MCP
-cutover. MCP integration, legacy-state migration and broader live qualification
-remain unfinished. School features depend on what each account can access.
+**Status:** `1.0.x` freezes the documented native library API. It does not claim
+completed MCP cutover, production-state migration or universal live-school
+compatibility. Those consumer/live gates remain separate. School features depend
+on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
 See [limitations](#supported-features-and-limitations) below.
 
 ## Install
 
-Install the exact candidate from PyPI once its gated publication completes:
+Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.0rc1
+python -m pip install librus-python-api==1.0.1
 ```
 
-An explicit version selects the prerelease without opting into every prerelease
-dependency. Before publication, use a checkout or locally built wheel instead.
+Pin the exact version qualified by your application. Before publication, use a
+checkout or locally built wheel instead.
 From a checkout, install into a virtual environment:
 
 ```sh
@@ -61,7 +67,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.0rc1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.0.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.
@@ -192,8 +198,10 @@ silently returning incomplete data. Cursors detect changes; they are not snapsho
 - **Notifications:** optional `NotificationStore` and `NotificationWorkflow`
   provide durable checkpoints, pending delivery and explicit acknowledgement.
 - **Persistent sends:** optional `PersistenceStore` records confirmations, claims
-  and uncertain outcomes across restarts. These stores require private POSIX
-  directories. Core reads do not create files.
+  and uncertain outcomes across restarts. Stores create or validate private
+  caller-selected directories; core reads do not create files. Use explicit
+  `files.prepare_attachment_directory(path)` to provision a private download
+  directory without writing platform-specific ACL code.
 
 The legacy and modern messaging backends have distinct references and permissions;
 select one explicitly. See the [API reference][api] for complete workflows.

{librus_python_api-1.0.0rc1 → librus_python_api-1.0.1}/README.md

@@ -8,25 +8,28 @@ Use it in personal scripts, notification services or application backends. One
 service can manage multiple logins while keeping their sessions and data separate.
 It is not an official Librus product.
 
-**Requirements:** Python 3.13 or newer. Linux and macOS are tested in CI.
-Persistence and saving attachments require POSIX filesystem features, such as
-those on Linux or macOS; Windows disk workflows are unsupported.
-
-**Status:** `1.0.0rc1`, a library-only beta prerelease, not stable 1.0 or an MCP
-cutover. MCP integration, legacy-state migration and broader live qualification
-remain unfinished. School features depend on what each account can access.
+**Requirements:** Python 3.13 or newer. Disk workflows require a trusted local
+POSIX filesystem on Linux/macOS, or a fixed local NTFS volume on Windows with
+private ACLs. Windows installations include `pywin32` and `tzdata` automatically.
+Network paths, reparse-point paths and unsafe storage permissions fail closed.
+See [platform requirements](contracts/persistence.md#windows-disk-boundary-25).
+
+**Status:** `1.0.x` freezes the documented native library API. It does not claim
+completed MCP cutover, production-state migration or universal live-school
+compatibility. Those consumer/live gates remain separate. School features depend
+on what each account can access. See the [compatibility policy](API.md#compatibility-policy).
 See [limitations](#supported-features-and-limitations) below.
 
 ## Install
 
-Install the exact candidate from PyPI once its gated publication completes:
+Install the exact release from PyPI after its gated publication completes:
 
 ```sh
-python -m pip install librus-python-api==1.0.0rc1
+python -m pip install librus-python-api==1.0.1
 ```
 
-An explicit version selects the prerelease without opting into every prerelease
-dependency. Before publication, use a checkout or locally built wheel instead.
+Pin the exact version qualified by your application. Before publication, use a
+checkout or locally built wheel instead.
 From a checkout, install into a virtual environment:
 
 ```sh
@@ -38,7 +41,7 @@ python -m pip install .
 To install a locally built wheel instead:
 
 ```sh
-python -m pip install ./dist/librus_python_api-1.0.0rc1-py3-none-any.whl
+python -m pip install ./dist/librus_python_api-1.0.1-py3-none-any.whl
 ```
 
 No CLI or background process is installed: import the library in your own program.
@@ -169,8 +172,10 @@ silently returning incomplete data. Cursors detect changes; they are not snapsho
 - **Notifications:** optional `NotificationStore` and `NotificationWorkflow`
   provide durable checkpoints, pending delivery and explicit acknowledgement.
 - **Persistent sends:** optional `PersistenceStore` records confirmations, claims
-  and uncertain outcomes across restarts. These stores require private POSIX
-  directories. Core reads do not create files.
+  and uncertain outcomes across restarts. Stores create or validate private
+  caller-selected directories; core reads do not create files. Use explicit
+  `files.prepare_attachment_directory(path)` to provision a private download
+  directory without writing platform-specific ACL code.
 
 The legacy and modern messaging backends have distinct references and permissions;
 select one explicitly. See the [API reference][api] for complete workflows.

{librus_python_api-1.0.0rc1 → librus_python_api-1.0.1}/pyproject.toml

@@ -11,16 +11,17 @@ requires-python = ">=3.13"
 license = "MIT"
 license-files = ["LICENSE"]
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 5 - Production/Stable",
   "Framework :: AsyncIO",
   "Intended Audience :: Developers",
   "Operating System :: POSIX",
   "Operating System :: MacOS :: MacOS X",
+  "Operating System :: Microsoft :: Windows",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
-dependencies = ["aiohttp>=3.14.2,<4", "lxml>=6.1,<7", "pydantic>=2.12,<3", "yarl>=1.20,<2"]
+dependencies = ["aiohttp>=3.14.2,<4", "lxml>=6.1,<7", "pydantic>=2.12,<3", "yarl>=1.20,<2", "pywin32>=312,<400; sys_platform == 'win32'", "tzdata>=2026.5; sys_platform == 'win32'"]
 
 [project.urls]
 Repository = "https://github.com/krzysztofbury/librus-python-api"
@@ -37,6 +38,7 @@ dev = [
   "ruff>=0.15,<0.17",
   "types-pyyaml>=6,<7",
   "types-lxml>=2026.2.16,<2027",
+  "types-pywin32>=312,<400",
   "pre-commit>=4.6,<5",
   "pip-audit>=2.10,<3",
 ]

{librus_python_api-1.0.0rc1 → librus_python_api-1.0.1}/src/librus_python_api/__init__.py

@@ -120,7 +120,7 @@ from librus_python_api.models import (
 from librus_python_api.sending import SendAttempt
 from librus_python_api.service import AccountClient, LibrusService
 
-__version__ = "1.0.0rc1"
+__version__ = "1.0.1"
 
 __all__ = [
     "AccountContext",

librus_python_api-1.0.1/src/librus_python_api/_notification_bootstrap.py

@@ -0,0 +1,124 @@
+"""Original bounded validation of caller-established, neutral offline mappings."""
+
+from dataclasses import asdict
+
+from librus_python_api._notification_codec import (
+    HEX,
+    canonical_notification_id,
+    dump,
+    validate_historical_item,
+)
+from librus_python_api.exceptions import ErrorKind, LibrusError
+from librus_python_api.models import NotificationCategory, RecentScheduleEvent
+from librus_python_api.notification_models import (
+    NotificationBaselineMapping,
+    NotificationBootstrap,
+    NotificationItem,
+    NotificationProvenance,
+    NotificationSeen,
+    NotificationState,
+)
+
+
+def prepare_bootstrap(
+    plan: NotificationBootstrap, per_category: int, batch_items: int, batch_bytes: int
+) -> tuple[
+    NotificationState,
+    tuple[NotificationItem, ...],
+    tuple[NotificationBaselineMapping, ...],
+]:
+    if type(plan.mappings) is not tuple or type(plan.pending_events) is not tuple:
+        raise LibrusError(ErrorKind.INVALID_INPUT)
+    if (
+        len(plan.mappings) > len(NotificationCategory) * per_category
+        or len(plan.pending_events) > batch_items
+    ):
+        raise LibrusError(ErrorKind.LIMIT)
+    seen, unmapped = _mapped_state(plan.mappings, per_category)
+    items: list[NotificationItem] = []
+    used = 2
+    agenda_ids = set(
+        next(
+            entry.identifiers
+            for entry in seen
+            if entry.category is NotificationCategory.AGENDA
+        )
+    )
+    for event in plan.pending_events:
+        if type(event) is not RecentScheduleEvent:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        item = NotificationItem(
+            NotificationCategory.AGENDA,
+            "0" * 64,
+            event,
+            None,
+            None,
+            NotificationProvenance.IMPORTED_HISTORY,
+        )
+        try:
+            validate_historical_item(item)
+        except LibrusError:
+            raise LibrusError(ErrorKind.INVALID_INPUT) from None
+        identifier = canonical_notification_id(NotificationCategory.AGENDA, event)
+        if identifier in agenda_ids:
+            # A conflict cannot silently consume an externally pending event.
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        agenda_ids.add(identifier)
+        final = NotificationItem(
+            item.category, identifier, event, None, None, item.provenance
+        )
+        used += len(
+            dump({"kind": "RecentScheduleEvent", "item": asdict(final)}, batch_bytes)
+        ) + bool(items)
+        if used > batch_bytes:
+            raise LibrusError(ErrorKind.LIMIT)
+        items.append(final)
+    if len(agenda_ids) > per_category:
+        raise LibrusError(ErrorKind.LIMIT)
+    return NotificationState(True, seen), tuple(items), unmapped
+
+
+def _mapped_state(
+    mappings: tuple[NotificationBaselineMapping, ...], per_category: int
+) -> tuple[tuple[NotificationSeen, ...], tuple[NotificationBaselineMapping, ...]]:
+    seen: dict[NotificationCategory, list[str]] = {
+        category: [] for category in NotificationCategory
+    }
+    sources: set[tuple[NotificationCategory, str]] = set()
+    native: set[tuple[NotificationCategory, str]] = set()
+    unmapped = []
+    counts = {category: 0 for category in NotificationCategory}
+    for mapping in mappings:
+        if (
+            type(mapping) is not NotificationBaselineMapping
+            or not isinstance(mapping.category, NotificationCategory)
+            or type(mapping.source_identifier) is not str
+            or not 1 <= len(mapping.source_identifier) <= 256
+        ):
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        try:
+            mapping.source_identifier.encode("utf-8")
+        except UnicodeError:
+            raise LibrusError(ErrorKind.INVALID_INPUT) from None
+        source = (mapping.category, mapping.source_identifier)
+        if source in sources:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        sources.add(source)
+        counts[mapping.category] += 1
+        if counts[mapping.category] > per_category:
+            raise LibrusError(ErrorKind.LIMIT)
+        identifier = mapping.native_identifier
+        if identifier is None:
+            unmapped.append(mapping)
+            continue
+        if type(identifier) is not str or HEX.fullmatch(identifier) is None:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        key = (mapping.category, identifier)
+        if key in native:
+            raise LibrusError(ErrorKind.INVALID_INPUT)
+        native.add(key)
+        seen[mapping.category].append(identifier)
+    return tuple(
+        NotificationSeen(category, tuple(identifiers))
+        for category, identifiers in seen.items()
+    ), tuple(unmapped)