jasil 0.1.0__tar.gz

jasil-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# OS
+.DS_Store
+Thumbs.db
+.vscode/
+.env
+.venv/
+
+# Python
+__pycache__/
+.ruff_cache/
+.hypothesis/
+.coverage
+coverage.json
+htmlcov/
+coverage.xml
+.pytest_cache/
+*.log
+.mypy_cache/
+.import_linter_cache/
+
+# local dev docs
+devdocs/
+
+# local dev scripts
+devscripts/
+
+# built documentation site (mkdocs)
+site/
+
+# build artifacts
+dist/
+*.egg-info/

jasil-0.1.0/CHANGELOG.md

@@ -0,0 +1,187 @@
+# Changelog
+
+All notable changes to JASIL are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+What counts as a breaking change — and what does not — is defined in
+[API stability](docs/api-stability.md). In short: the `jasil` namespace, the
+capability provider protocols, the event envelope, the capability URI schemes,
+and the database schema of JASIL's own tables are covered by SemVer; anything
+under `jasil._core`, log message text, and the wording of error messages are not.
+
+## [0.1.0]
+
+First release. Extracted from [Endurain](https://github.com/endurain-project/endurain),
+where this code ran in production as an internal `infra` package. The API is
+still settling: `0.x` releases may break it, and the SemVer guarantees in
+[API stability](docs/api-stability.md) begin at `1.0.0`.
+
+### Added
+
+**Capability providers and backends**
+
+- `StateProvider` — ephemeral keyed state with TTLs, backed by process-local
+  memory (`memory://`) or Redis (`redis://` / `rediss://` / `unix://`). Beyond
+  plain key/value access it exposes the atomic primitives correctness actually
+  depends on — `set_if_absent`, `get_and_delete`, and `record_tiered_failure`
+  (an atomic tiered lockout, implemented under a lock in memory and as a Lua
+  script on Redis) — so a store behaves identically on either backend.
+- `StorageProvider` — opaque blob storage addressed by `(area, key)`, backed by
+  the local filesystem (`local://`) or S3-compatible object storage (`s3://`).
+  Both backends refuse the same addresses — empty, absolute, or containing a
+  `..` component — before touching a disk or a client, so the contract a caller
+  sees does not change with the deployment. `list_keys` is recursive on both, so
+  a nested key is listed wherever it is stored.
+- `EventBusProvider` — synchronous in-process dispatch (`memory://`) or Redis
+  Streams with a consumer group (`redis://`), giving competing-consumer
+  semantics across replicas.
+- `LockProvider` — a no-op lock (`noop://`) or PostgreSQL session-level advisory
+  locks (`postgres-advisory://`), which need no infrastructure beyond the
+  database the host already has.
+- `ClockProvider` and `GeocodingProvider`, the latter covering Nominatim,
+  Photon, and geocode.maps.co behind one interface.
+- A Redis outage surfaces to callers as `StateBackendUnavailableError`, so
+  domain code never imports or catches a redis-py exception.
+
+**Deployment profiles**
+
+- `local`, `distributed`, and `custom` profiles. The profile supplies the
+  default for each capability URI, and the `local` profile is the zero-config
+  default: memory state, local disk, in-process events, no-op lock.
+- `distributed` and `custom` **refuse to start** when a capability URI is unset
+  rather than falling back to a process-local backend, which across replicas
+  would diverge silently — the failure the profile system exists to prevent.
+- A startup capability report showing how each capability resolved and why, plus
+  consistency checks that reject a multi-process topology wired to
+  process-local state. `build_platform()` runs both before it constructs a single
+  backend; set `enforce_deployment_consistency=False` to downgrade a refusal to a
+  warning.
+
+**Events**
+
+- One immutable `Event` envelope with an ISO-8601 UTC timestamp, a UUIDv4 id
+  stable across retries, and a caller-owned `metadata` dict.
+- `event_id`, `event_type` and `source` are length-checked when the envelope is
+  minted, and `subscriber_id` when a durable subscriber registers, so a value
+  too long for the column it is persisted in raises at the producing call site
+  instead of failing at the write — where PostgreSQL and MySQL raise, SQLite
+  does not, and the publish seam swallows the failure either way. `payload` and
+  `metadata` are deliberately *not* capped; see the events documentation for what
+  belongs in them.
+- Payload schema versioning: `VersionedPayload` carries a `SCHEMA_VERSION` and
+  per-step `UPGRADERS`. A payload written by an older build is walked forward
+  one version at a time; one written by a *newer* build is refused rather than
+  silently misread — the failure mode during a rolling deploy.
+- `publisher.publish` is the single publish seam. Delivery failures are logged
+  and swallowed so a publish never breaks the producer.
+- `publish_committing` / `publish_many_committing` own the commit ordering, so
+  durable delivery can be made atomic with the caller's domain write.
+- `subscribers.best_effort` wraps a raising handler into a swallowing bus
+  subscriber, so derived work can never fail the request that produced the event.
+
+**Durable jobs**
+
+- A transactional outbox relayed into leased per-subscriber jobs, with
+  exponential backoff (equal jitter, to avoid a retry stampede), an attempt
+  ceiling, and a dead-letter queue with replay.
+- Idempotent consumers: `(event_id, subscriber_id)` uniqueness is enforced by
+  the database, so a re-delivered event never runs a subscriber twice.
+- Lease reclamation returns work stranded by a crashed worker; an attempt is
+  counted at claim time, which is what bounds a crash loop.
+- A worker's identity is bounded to the width of the lease column it is written
+  to. When a long hostname forces truncation it carries a digest of the full
+  value, so two machines sharing a hostname prefix never collapse onto one lease
+  holder — which would hand each of them the other's claimed rows.
+- On PostgreSQL, claiming and relaying use `FOR UPDATE SKIP LOCKED` so
+  concurrent workers and relayers take disjoint batches with no coordinating lock.
+- `DurableSubscriberNet` declares the reconciliation net — a scheduled backfill,
+  or a documented exemption — that every subscriber writing durable derived state
+  owes, since delivery is at-least-once but not guaranteed. `assert_nets_complete`
+  holds the whole registry to it, so a missing net fails your own test suite
+  rather than surfacing in production.
+
+**Observability**
+
+- An `event_log` table recording each event's lifecycle, written by the bus and
+  the publish facade, with dashboard aggregates.
+- Identifiers that are too long for the column they are persisted in are refused
+  at the producing call site; derived, diagnostic values (failure text, the
+  joined subscriber list, a worker identity) are truncated with a marker instead,
+  so a reader can tell the value was cut.
+- Retention pruning in bounded batches, on independently configurable windows.
+  In-flight rows and dead-letters are never pruned. Register it with
+  `jasil.retention.schedule_retention_maintenance(scheduler)`, the counterpart of
+  `jasil.jobs.service.schedule_job_maintenance` — separate because retention also
+  covers the `event_log`, so it applies without durable jobs.
+
+**Host integration**
+
+- The **host** owns the declarative base and the engine. JASIL maps its tables
+  into the host's registry via `map_models(Base)` and takes a session factory via
+  `configure_sessionmaker(...)`. JASIL never creates an engine.
+  `map_models` must run before `jasil.jobs.crud` or `jasil.event_log.crud` is
+  imported; every other public module — `jasil.publisher` above all, which every
+  producer imports at module scope — defers its model imports and is safe to
+  import from anywhere in the host's import graph.
+- `jasil.settings` — immutable, grouped configuration installed by the host.
+  JASIL reads no environment variables and no secret files.
+- `jasil.correlation` — a pluggable correlation-id provider, defaulting to a
+  module-local context variable, so events carry the host's request id.
+- Packaged Alembic revisions (`jasil[migrations]`) on their own version table,
+  `jasil_alembic_version`, scoped to JASIL's tables so the host's Alembic
+  history and tables are never touched.
+- FastAPI dependency helpers behind the `fastapi` extra, resolving
+  `app.state.platform` when the host attached one and otherwise the process-wide
+  platform, so the quick-start wiring needs nothing extra.
+- `jasil.admin` — the operator-facing surface: `get_jobs_summary`,
+  `get_event_log_summary`, and `replay_dead_letter_job`, plus the response
+  schemas. Importable from anywhere in the host's import graph and takes no
+  session, so an admin route cannot hand JASIL its own open transaction. The
+  CRUD modules behind it stay internal.
+- `jasil.testing` — `FixedClock`, `install_test_platform`, and `reset_all`, so a
+  host's suite does not have to rediscover which process-wide slots JASIL
+  installs. `reset_all` deliberately leaves the ORM mapping in place; model
+  modules capture the declarative base at import time.
+- `Platform.close()` releases what the platform owns — the event-bus consumer
+  thread and the shared Redis clients — and never raises, so a shutdown failure
+  cannot mask whatever prompted the shutdown. The durable-job worker and the
+  host's engine are stopped separately, because the platform does not own them.
+- `jasil.lifecycle.shutdown()` composes the two halves of that in the order that
+  matters — the worker stops before the bus its subscribers publish through — so
+  a host does not have to know the ordering. Idempotent, safe before anything has
+  started, and never raises.
+
+**Packaging**
+
+- A core install requires only `sqlalchemy` and `pydantic`. Every backend client
+  lives behind an extra (`redis`, `s3`, `postgres`, `jobs`, `fastapi`,
+  `geocoding`, `migrations`, `all`) and is imported lazily, so a single-process
+  deployment loads none of them.
+- Ships `py.typed`.
+
+### Security
+
+- SSRF guard on every outbound host JASIL dials on the host's behalf. All
+  resolved addresses must be public unicast — a single private, loopback,
+  link-local, or reserved answer rejects the host, which is what defends against
+  DNS rebinding. An allowlist escape hatch exists for self-hosted services on
+  private networks, and every use of it is logged for audit. Configured values
+  must be a bare `host[:port]`, so one carrying a scheme or path cannot redirect
+  a request elsewhere. An allowlist entry that is a *hostname* exempts every
+  address that name resolves to, so taking one is logged at `WARNING` naming the
+  address and recommending a CIDR; a CIDR exemption logs at `INFO`.
+- The geocoding backend refuses redirects, so a permitted host cannot 3xx-pivot
+  onto an internal target. Its response body is read under a size cap, and its
+  failures are logged by exception type and status code only: `requests` puts the
+  request URL in an error message, and that URL carries the API key.
+- The Redis state backend escapes glob metacharacters before turning a caller's
+  key prefix into a `SCAN`/`MATCH` pattern, so a prefix holding `*`, `?` or
+  `[...]` matches only itself and never widens onto keys the caller did not name.
+  A prefix built from a tenant or user identifier is therefore safe.
+- The local storage backend rejects absolute and parent-traversal area and key
+  values before any filesystem access, and percent-encodes both into the URL it
+  returns, so a key holding `?`, `#` or `%` cannot alter the URL it lands in.
+
+[0.1.0]: https://github.com/endurain-project/jasil/releases/tag/v0.1.0

jasil-0.1.0/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright (c) 2025 João Vitória Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

jasil-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: jasil
+Version: 0.1.0
+Summary: Just Another Substrate & Infrastructure Library
+Project-URL: Homepage, https://jasil.endurain.com/
+Project-URL: Documentation, https://jasil.endurain.com/
+Project-URL: Repository, https://github.com/endurain-project/jasil
+Project-URL: Changelog, https://github.com/endurain-project/jasil/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/endurain-project/jasil/issues
+Project-URL: Security, https://github.com/endurain-project/jasil/blob/main/SECURITY.md
+Author-email: João Vitória Silva <joao@endurain.com>
+License: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.12
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: sqlalchemy>=2.0.49
+Provides-Extra: all
+Requires-Dist: alembic>=1.13; extra == 'all'
+Requires-Dist: apscheduler>=3.10.2; extra == 'all'
+Requires-Dist: boto3>=1.34.0; extra == 'all'
+Requires-Dist: fastapi>=0.136.0; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'all'
+Requires-Dist: redis>=5.0.0; extra == 'all'
+Requires-Dist: requests>=2.32.4; extra == 'all'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.136.0; extra == 'fastapi'
+Provides-Extra: geocoding
+Requires-Dist: requests>=2.32.4; extra == 'geocoding'
+Provides-Extra: jobs
+Requires-Dist: apscheduler>=3.10.2; extra == 'jobs'
+Provides-Extra: migrations
+Requires-Dist: alembic>=1.13; extra == 'migrations'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == 'redis'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34.0; extra == 's3'
+Description-Content-Type: text/markdown
+
+# JASIL
+
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/endurain-project/jasil/blob/main/LICENSE.md)
+[![Release](https://img.shields.io/github/v/release/endurain-project/jasil?label=release&color=blue)](https://github.com/endurain-project/jasil/releases)
+[![PyPI version](https://img.shields.io/pypi/v/jasil)](https://pypi.org/project/jasil/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/jasil)](https://pypi.org/project/jasil/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/jasil/)
+[![Docs](https://img.shields.io/badge/docs-jasil.endurain.com-blue)](https://jasil.endurain.com/)
+[![Stars](https://img.shields.io/github/stars/endurain-project/jasil?label=stars&logo=github)](https://github.com/endurain-project/jasil)
+
+**J**ust **A**nother **S**ubstrate & **I**nfrastructure **L**ibrary — a
+framework-agnostic infrastructure substrate for Python services: swappable
+capability backends, an event pipeline, durable jobs, and observability.
+
+> **Status:** `0.1.0` — the API is still settling. Expect breaking changes on
+> minor versions until `1.0.0`.
+
+---
+
+## What it gives you
+
+| Layer | What it does |
+|---|---|
+| **Providers** | Small protocols — state, storage, events, lock, clock, geocoding — that your domain code depends on instead of on Redis, S3, or Postgres. |
+| **Backends** | A working implementation of each, selected by URI: `memory://` or `redis://`, `local://` or `s3://`, `noop://` or `postgres-advisory://`. |
+| **Deployment profiles** | `local` runs single-process with zero extra infrastructure. `distributed` requires shared backends and refuses to guess them. |
+| **Event pipeline** | One envelope, one publish seam, payload schema versioning that survives a rolling deploy. |
+| **Durable jobs** | A transactional outbox relayed into leased per-subscriber jobs, with exponential backoff and a dead-letter queue. |
+| **Observability** | An event lifecycle log and bounded retention pruning for every table it owns. |
+
+A core install depends on **`sqlalchemy` and `pydantic` only**. Every backend
+client lives behind an extra and is imported lazily, so a single-process
+deployment never loads `redis`, `boto3`, or `requests`.
+
+> **JASIL is synchronous.** Every provider, subscriber, and the durable-jobs
+> layer is blocking Python, and the ORM integration expects a synchronous
+> `sessionmaker` — there is no `AsyncSession` support. On an async framework,
+> call into JASIL from a worker thread (a `def` FastAPI route or dependency does
+> this for you). See [the docs](https://jasil.endurain.com/#one-thing-it-cannot-do-yet).
+
+## Installation
+
+```bash
+pip install jasil                    # core: memory / local disk / in-process
+pip install "jasil[redis,s3]"        # distributed state, events and storage
+pip install "jasil[all]"             # every optional backend
+```
+
+| Extra | Enables |
+|---|---|
+| `redis` | Redis state store and Redis-Streams event bus |
+| `s3` | S3-compatible object storage |
+| `postgres` | PostgreSQL advisory locks |
+| `jobs` | Durable-job scheduling |
+| `fastapi` | `Depends` helpers exposing the providers to routes |
+| `geocoding` | HTTP reverse geocoding |
+| `migrations` | Packaged Alembic revisions |
+
+### Verifying a release
+
+Releases are built and published by [this repository's release workflow](.github/workflows/publish-jasil.yml) through PyPI Trusted Publishing, with [PEP 740](https://peps.python.org/pep-0740/) attestations. You can confirm a downloaded artifact came from that workflow and was not substituted:
+
+```bash
+uvx pypi-attestations verify pypi \
+  --repository https://github.com/endurain-project/jasil \
+  pypi:jasil-<version>-py3-none-any.whl
+```
+
+A successful run prints `OK: <filename>`. `Provenance for file ... was not found` means the artifact predates attested publishing rather than that verification failed.
+
+Each release run also produces a CycloneDX SBOM and `SHA256SUMS`, generated from a clean install of the built wheel. These are retained as workflow artifacts on the release run rather than published to PyPI.
+
+## Quick start
+
+JASIL never reads your environment, creates your engine, or owns your
+declarative base — the host supplies all three.
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
+
+import jasil.orm as jasil_orm
+import jasil.settings as jasil_settings
+from jasil.container import build_platform
+from jasil.runtime import set_active_platform
+
+
+class Base(DeclarativeBase):
+    """Your application's declarative base."""
+
+
+# 1. Map JASIL's tables into your registry, before any database use.
+jasil_orm.map_models(Base)
+
+# 2. Hand JASIL a session factory bound to your engine.
+engine = create_engine("postgresql+psycopg://...")
+jasil_orm.configure_sessionmaker(sessionmaker(bind=engine))
+
+# 3. Configure, build, publish.
+jasil_settings.configure(jasil_settings.JasilSettings(data_dir="/srv/data"))
+set_active_platform(build_platform())
+```
+
+Then depend on capabilities, not on infrastructure:
+
+```python
+from jasil.runtime import get_active_platform
+
+platform = get_active_platform()
+platform.state.set("session:abc", b"...", ttl_seconds=3600)
+platform.storage.save("thumbnails", "42.webp", image_bytes)
+
+with platform.lock.try_acquire("nightly-backfill") as acquired:
+    if acquired:
+        run_backfill()
+```
+
+Publishing an event goes through one seam, so switching from best-effort
+delivery to a transactional outbox is a configuration change, not a rewrite:
+
+```python
+from jasil.publisher import publish
+
+publish("activity.created", {"activity_id": 42}, source="api:store_activity", db=db)
+```
+
+## Going distributed
+
+Change the profile and point the capability URIs at real infrastructure:
+
+```python
+jasil_settings.configure(
+    jasil_settings.JasilSettings(
+        profile=jasil.DeploymentProfile.DISTRIBUTED,
+        state_uri="redis://cache:6379/0",
+        events_uri="redis://cache:6379/1",
+        storage_uri="s3://my-bucket",
+        lock_uri="postgres-advisory://",
+    )
+)
+```
+
+The `distributed` profile **refuses to start** if a capability URI is unset. A
+silent fallback to a process-local backend across replicas is the failure the
+profile system exists to prevent.
+
+## Development
+
+```bash
+uv sync --all-extras --group dev
+uv run pytest              # tests + coverage gate
+uv run ruff check .        # lint
+uv run mypy                # type check
+uv run lint-imports        # architectural import contracts
+```
+
+## Documentation
+
+Full documentation is available at the [JASIL docs site](https://jasil.endurain.com/).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guidelines](CONTRIBUTING.md) for guidelines.
+
+<div align="center">
+  <sub>Built with ❤️ from Portugal | Part of the <a href="https://github.com/endurain-project">Endurain</a> ecosystem</sub>
+</div>

jasil-0.1.0/README.md

@@ -0,0 +1,171 @@
+# JASIL
+
+[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/endurain-project/jasil/blob/main/LICENSE.md)
+[![Release](https://img.shields.io/github/v/release/endurain-project/jasil?label=release&color=blue)](https://github.com/endurain-project/jasil/releases)
+[![PyPI version](https://img.shields.io/pypi/v/jasil)](https://pypi.org/project/jasil/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/jasil)](https://pypi.org/project/jasil/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/jasil/)
+[![Docs](https://img.shields.io/badge/docs-jasil.endurain.com-blue)](https://jasil.endurain.com/)
+[![Stars](https://img.shields.io/github/stars/endurain-project/jasil?label=stars&logo=github)](https://github.com/endurain-project/jasil)
+
+**J**ust **A**nother **S**ubstrate & **I**nfrastructure **L**ibrary — a
+framework-agnostic infrastructure substrate for Python services: swappable
+capability backends, an event pipeline, durable jobs, and observability.
+
+> **Status:** `0.1.0` — the API is still settling. Expect breaking changes on
+> minor versions until `1.0.0`.
+
+---
+
+## What it gives you
+
+| Layer | What it does |
+|---|---|
+| **Providers** | Small protocols — state, storage, events, lock, clock, geocoding — that your domain code depends on instead of on Redis, S3, or Postgres. |
+| **Backends** | A working implementation of each, selected by URI: `memory://` or `redis://`, `local://` or `s3://`, `noop://` or `postgres-advisory://`. |
+| **Deployment profiles** | `local` runs single-process with zero extra infrastructure. `distributed` requires shared backends and refuses to guess them. |
+| **Event pipeline** | One envelope, one publish seam, payload schema versioning that survives a rolling deploy. |
+| **Durable jobs** | A transactional outbox relayed into leased per-subscriber jobs, with exponential backoff and a dead-letter queue. |
+| **Observability** | An event lifecycle log and bounded retention pruning for every table it owns. |
+
+A core install depends on **`sqlalchemy` and `pydantic` only**. Every backend
+client lives behind an extra and is imported lazily, so a single-process
+deployment never loads `redis`, `boto3`, or `requests`.
+
+> **JASIL is synchronous.** Every provider, subscriber, and the durable-jobs
+> layer is blocking Python, and the ORM integration expects a synchronous
+> `sessionmaker` — there is no `AsyncSession` support. On an async framework,
+> call into JASIL from a worker thread (a `def` FastAPI route or dependency does
+> this for you). See [the docs](https://jasil.endurain.com/#one-thing-it-cannot-do-yet).
+
+## Installation
+
+```bash
+pip install jasil                    # core: memory / local disk / in-process
+pip install "jasil[redis,s3]"        # distributed state, events and storage
+pip install "jasil[all]"             # every optional backend
+```
+
+| Extra | Enables |
+|---|---|
+| `redis` | Redis state store and Redis-Streams event bus |
+| `s3` | S3-compatible object storage |
+| `postgres` | PostgreSQL advisory locks |
+| `jobs` | Durable-job scheduling |
+| `fastapi` | `Depends` helpers exposing the providers to routes |
+| `geocoding` | HTTP reverse geocoding |
+| `migrations` | Packaged Alembic revisions |
+
+### Verifying a release
+
+Releases are built and published by [this repository's release workflow](.github/workflows/publish-jasil.yml) through PyPI Trusted Publishing, with [PEP 740](https://peps.python.org/pep-0740/) attestations. You can confirm a downloaded artifact came from that workflow and was not substituted:
+
+```bash
+uvx pypi-attestations verify pypi \
+  --repository https://github.com/endurain-project/jasil \
+  pypi:jasil-<version>-py3-none-any.whl
+```
+
+A successful run prints `OK: <filename>`. `Provenance for file ... was not found` means the artifact predates attested publishing rather than that verification failed.
+
+Each release run also produces a CycloneDX SBOM and `SHA256SUMS`, generated from a clean install of the built wheel. These are retained as workflow artifacts on the release run rather than published to PyPI.
+
+## Quick start
+
+JASIL never reads your environment, creates your engine, or owns your
+declarative base — the host supplies all three.
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
+
+import jasil.orm as jasil_orm
+import jasil.settings as jasil_settings
+from jasil.container import build_platform
+from jasil.runtime import set_active_platform
+
+
+class Base(DeclarativeBase):
+    """Your application's declarative base."""
+
+
+# 1. Map JASIL's tables into your registry, before any database use.
+jasil_orm.map_models(Base)
+
+# 2. Hand JASIL a session factory bound to your engine.
+engine = create_engine("postgresql+psycopg://...")
+jasil_orm.configure_sessionmaker(sessionmaker(bind=engine))
+
+# 3. Configure, build, publish.
+jasil_settings.configure(jasil_settings.JasilSettings(data_dir="/srv/data"))
+set_active_platform(build_platform())
+```
+
+Then depend on capabilities, not on infrastructure:
+
+```python
+from jasil.runtime import get_active_platform
+
+platform = get_active_platform()
+platform.state.set("session:abc", b"...", ttl_seconds=3600)
+platform.storage.save("thumbnails", "42.webp", image_bytes)
+
+with platform.lock.try_acquire("nightly-backfill") as acquired:
+    if acquired:
+        run_backfill()
+```
+
+Publishing an event goes through one seam, so switching from best-effort
+delivery to a transactional outbox is a configuration change, not a rewrite:
+
+```python
+from jasil.publisher import publish
+
+publish("activity.created", {"activity_id": 42}, source="api:store_activity", db=db)
+```
+
+## Going distributed
+
+Change the profile and point the capability URIs at real infrastructure:
+
+```python
+jasil_settings.configure(
+    jasil_settings.JasilSettings(
+        profile=jasil.DeploymentProfile.DISTRIBUTED,
+        state_uri="redis://cache:6379/0",
+        events_uri="redis://cache:6379/1",
+        storage_uri="s3://my-bucket",
+        lock_uri="postgres-advisory://",
+    )
+)
+```
+
+The `distributed` profile **refuses to start** if a capability URI is unset. A
+silent fallback to a process-local backend across replicas is the failure the
+profile system exists to prevent.
+
+## Development
+
+```bash
+uv sync --all-extras --group dev
+uv run pytest              # tests + coverage gate
+uv run ruff check .        # lint
+uv run mypy                # type check
+uv run lint-imports        # architectural import contracts
+```
+
+## Documentation
+
+Full documentation is available at the [JASIL docs site](https://jasil.endurain.com/).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.
+
+## Contributing
+
+Contributions welcome! See [Contributing Guidelines](CONTRIBUTING.md) for guidelines.
+
+<div align="center">
+  <sub>Built with ❤️ from Portugal | Part of the <a href="https://github.com/endurain-project">Endurain</a> ecosystem</sub>
+</div>

jasil-0.1.0/SECURITY.md

@@ -0,0 +1,49 @@
+# Security policy
+
+## Supported versions
+
+JASIL is at `0.x`. Security fixes are released against the latest published
+version only; there are no maintained release branches yet. Once `1.0.0` ships,
+this section will state a support window.
+
+| Version | Supported |
+|---|---|
+| `0.1.x` | Yes |
+| `< 0.1` | No |
+
+## Scope
+
+In scope: anything in the `jasil` package. That includes the SSRF guard on
+outbound hosts, the path-traversal checks in the local storage backend, and any
+way a host application's data could be exposed, corrupted, or lost through
+JASIL's own code.
+
+Out of scope: vulnerabilities in an application that *uses* JASIL but stem from
+its own code or configuration — for example allow-listing an internal host via
+`NetworkSettings.ssrf_allowed_hosts` and then dialing it. Report those to that
+application's maintainers.
+
+Vulnerabilities in a dependency should be reported upstream first. If JASIL's use
+of it makes the impact materially worse, report that here too.
+
+## Reporting a vulnerability
+
+1. **Do not** open a public issue.
+2. Email <joao@endurain.com> with the details.
+3. Include:
+   - steps to reproduce;
+   - the affected version;
+   - potential impact;
+   - any suggested fix, if you have one.
+4. You will get an acknowledgement when possible.
+
+Please include as much detail as you can — it is what makes a report actionable
+rather than a starting point for investigation.
+
+## What to expect
+
+This project is maintained by one person in their spare time, so response times
+vary. A fix will be released as soon as it is ready, and the advisory will credit
+you unless you would rather stay anonymous.
+
+Thank you for helping keep this project secure.