siphrix 1.0.0__tar.gz

siphrix-1.0.0/CHANGELOG.md

@@ -0,0 +1,433 @@
+# Changelog
+
+## Unreleased — rebrand to Siphrix
+
+### Product rename: AlterSpec → Siphrix
+- renamed the Python package, console script, and PyPI distribution
+  from `alterspec` to `siphrix` (`import siphrix`, `siphrix ...`)
+- renamed the operator environment-variable contract from
+  `ALTERSPEC_*` to `SIPHRIX_*` and the default runtime home from
+  `~/.alterspec` to `~/.siphrix` (clean break — pre-beta, no migration
+  shim; existing `~/.alterspec` state is not auto-migrated)
+- renamed all brand strings in CLI/console output, docs, and fixtures
+  (21,238 occurrences across 1,331 files); `git mv alterspec siphrix`
+  for the package tree plus the dashboard/docs/installer/research paths
+- no behaviour change: the policy engine, runtime, contracts, schema
+  identifiers, and reason codes are unchanged; the full suite
+  (29,864 passed, 16 skipped) and `release_check.py` (PUBLISH OK) are
+  green on the renamed package
+- external follow-up (not an in-repo change): the GitHub repository
+  must be renamed to `siphrix` for the rewritten project URLs to
+  resolve
+
+## v1.0.0 — final release structure
+
+### Release-grade reorganization
+- consolidated the canonical integration library into `siphrix.integrations`
+  (`audit`, `layer_utils`, `snapshot`); the former `siphrix.examples.*`
+  modules remain as backward-compatibility re-export shims
+- moved `role_policy_resolver` into the package at
+  `siphrix.policy_packs.resolver`; policy pack YAMLs (`safe_defaults`,
+  `enterprise_defaults`, `dev_agent_defaults`) and role overlays
+  (`admin`, `developer`, `finance`, `support`) are now shipped as package data
+- relocated demo agents (`app.py`, `demo_scenarios.py`, `example_agent.py`,
+  `example_agent_openai.py`) to `examples/` at the repo root (not packaged)
+- relocated the operator control panel to `tools/integration_control_panel.py`
+  and dev scripts to `scripts/` (not packaged)
+- moved `POLICY_VERSIONING_ARCHITECTURE.md` to `docs/architecture/`
+- moved v3/v4 compatibility policy fixtures to `tests/fixtures/policies/compat/`
+
+### Runtime side-effect isolation
+- `siphrix.logs.logger` and `siphrix.state.state_manager` now write to
+  `~/.siphrix/` by default; `SIPHRIX_HOME`, `SIPHRIX_LOG_PATH`, and
+  `SIPHRIX_STATE_PATH` override the paths
+- `siphrix.policy_remote`, `siphrix.trust.policy_remote_guard`,
+  `siphrix.policy_sources.source`, and `siphrix.engine.runner_profiles`
+  no longer write into the package source tree; all defaults resolve under
+  `~/.siphrix/` with matching env-var overrides
+- `siphrix.memory.api` no longer defaults to the package-local path
+  `siphrix/memory/memory_store.json`; the canonical default is now
+  `$SIPHRIX_HOME/memory/memory_store.json` (defaulting to
+  `~/.siphrix/memory/memory_store.json`), resolved via the new
+  `siphrix.runtime_paths` helper. The parent directory is created on
+  first use; a legacy repo-local seed is migrated verbatim only when the
+  canonical runtime file does not yet exist
+
+### Trust posture
+- introduced `siphrix.trust.trust_mode` with two explicit postures:
+  `development` (default) and `hardened` (requires
+  `$SIPHRIX_TRUST_SEAL_SECRET` ≥ 32 bytes or an explicit caller
+  argument; fails closed with stable `trust_seal_secret_missing` /
+  `trust_seal_secret_too_short` codes)
+- `siphrix.trust.trust_seal` now routes secret resolution through the
+  posture resolver; hardened-mode sign / verify never falls back to the
+  development default. The historical `DEFAULT_TRUST_SEAL_SECRET`
+  constant is preserved as a development-only alias of the built-in
+  development secret for backwards compatibility
+- added `siphrix.readiness.checks.check_trust_posture`; wired into
+  `siphrix.doctor.run_doctor` (canonical check count 4 → 5) and into
+  the `ALL_CHECKS` tuple in readiness (8 → 9)
+- documented the reference remote-policy server as a development /
+  reference surface only, with an explicit tie-in to the trust-mode
+  concept
+
+### Readiness / doctor launch gate
+- added `siphrix.readiness.checks.check_runtime_paths` — verifies
+  canonical runtime path resolution and guards against regressions
+  where a resolved path would fall inside the installed package tree
+- added `siphrix.readiness.checks.check_runtime_home_writable` — real
+  write-probe against `ensure_siphrix_home()` (creates + writes +
+  reads + removes a short marker file); `UNHEALTHY` if the runtime
+  home cannot be created or written
+- `ALL_CHECKS` tuple grew from 9 → 11 entries; `test_point11_readiness`
+  count assertion updated
+- `check_core_package` in `siphrix.doctor` now also reports a
+  `DEGRADED` posture when `siphrix.__version__` diverges from
+  `pyproject.toml`'s `[project].version` (repo / editable installs only)
+- `assess_system_readiness` now injects a structured
+  `metadata["launch_readiness"]` with two booleans
+  (`development_ready` / `production_ready`) plus per-gate `blocking`
+  subsystem lists. `production_ready` requires every check HEALTHY
+  *and* `trust_posture.production_ready=True`
+- new `siphrix.readiness.format_report` — compact operator-grade
+  text renderer for human / CI logs. JSON consumers continue to use
+  `SystemHealthReport.to_dict()`
+- the doctor surface (`siphrix doctor` / `run_doctor`) inherits the
+  launch-readiness metadata automatically; 3 live postures verified
+  (dev default, hardened-missing-secret, hardened-configured)
+
+### CLI polish
+- top-level description updated to
+  "Siphrix — AI Action Firewall & Policy Runtime."
+- `--help` now includes a stable `examples:` epilog, a brief
+  launch-gate note, and a trust-posture note — every subcommand stays
+  visible under `positional arguments`
+- **new `siphrix doctor --json`** — emits the full
+  `SystemHealthReport.to_dict()` as JSON (indent=2, sort_keys=True)
+  with no text preamble, so `siphrix doctor --json | jq
+  .metadata.launch_readiness.production_ready` works as a CI gate
+- `siphrix doctor` text mode now uses the shared
+  `siphrix.readiness.format_report`, which renders the
+  launch-readiness block alongside the per-subsystem status lines.
+  The legacy `siphrix doctor: <summary>` first line is preserved
+  so existing scripts that grep for it keep working
+- `format_report` status glyphs realigned to the full-word format
+  already pinned by the CLI test surface
+  (`[HEALTHY]`/`[DEGRADED]`/`[UNHEALTHY]`/`[SKIPPED]`)
+- exit code contract for `siphrix doctor` unchanged: `0` on `READY`
+  or `DEGRADED`, `1` on `NOT_READY`; JSON mode propagates the same
+  exit code so CI jobs gate correctly regardless of output format
+
+### Examples: official golden-path demo
+- **new `examples/official_demo.py`** — the official Siphrix product
+  demo. A single provider-neutral script with three tightly curated
+  flows in one run:
+    1. **Demo 1 — Blocked unsafe action**: a destructive `file_delete`
+       is blocked under the shipped `safe_defaults` pack
+       (`blocked_by_global:file_delete_blocked_by_pack`, matched rule
+       `block_file_delete`).
+    2. **Demo 2 — Allowed safe action**: a read-only `file_read` is
+       explicitly allowed (`allow_all_layers`, matched rule
+       `allow_file_read`).
+    3. **Demo 3 — Auditable decisions + launch-readiness posture**:
+       prints the decision trail (with `decision_id` and reason codes)
+       and the `siphrix doctor` launch-readiness block.
+  No third-party SDK, no network, no API keys. Runs entirely against
+  the shipped policy pack translated on the fly via
+  `siphrix.policy_packs.export_policy_pack`.
+- `examples/example_agent_openai.py` now carries a prominent
+  module docstring marking it as optional / provider-specific (requires
+  `pip install openai` and a valid `OPENAI_API_KEY`). The golden path
+  is provider-neutral.
+- README Quickstart updated to introduce `python examples/official_demo.py`
+  as the official one-command demo; existing references to
+  `basic_agent`, `tool_calling`, `universal_pattern` are preserved as
+  the three focused single-shape walkthroughs.
+- new `tests/test_official_demo_smoke.py` — 7 tests pinning the
+  golden-path contract: exit code, three-banner layout, BLOCK/ALLOW
+  verdicts with their decision_ids and matched-rule ids, doctor
+  launch-readiness block, no `SIPHRIX_POLICY_FILE` leak into the
+  parent process, no `openai` SDK import.
+
+### Packaging / install surface
+- **new `siphrix demo` CLI subcommand** — the official golden-path
+  product demo is now reachable from any `pip install siphrix` as
+  `siphrix demo`. The demo core moved into the installable package
+  at `siphrix/cli/demo.py`; `examples/official_demo.py` is now a
+  thin wrapper over `siphrix.cli.demo.main` so both invocation
+  styles run byte-identical code.
+- `pyproject.toml` metadata tightened:
+    - `description` now reads
+      "Siphrix — AI Action Firewall & Policy Runtime. Evaluates
+      every agent action against a policy before execution, emits an
+      auditable decision trail, and fails closed when in doubt."
+    - 10-entry `keywords` list (`ai`, `ai-agents`, `ai-safety`,
+      `action-firewall`, `policy-engine`, `policy-runtime`,
+      `governance`, `audit`, `enforcement`, `fail-closed`).
+    - Full `classifiers` block: MIT License, Python 3.11–3.14,
+      Production/Stable, Typed, Security + Monitoring topics.
+    - `project.urls` now includes `Homepage` and `Issues` alongside
+      the existing `Repository` / `Documentation` / `Changelog`.
+    - New `[project.optional-dependencies].build = ["build>=1.0",
+      "twine>=5.0"]` so operators can `pip install siphrix[build]`
+      for release tooling.
+- `siphrix.cli.demo` ships as part of the wheel (confirmed 778
+  entries, `siphrix/cli/demo.py` present). Entry point remains
+  `siphrix = siphrix.cli.app:main`.
+- `siphrix.cli.demo.main` now scopes both `SIPHRIX_POLICY_FILE`
+  and `SIPHRIX_NO_SIDE_EFFECTS` so the demo narrative is stable
+  regardless of the caller's ambient environment. Variables are
+  restored to their original values in `finally`.
+- Fixed a pre-existing test-isolation leak in
+  `ConfigIntegrationTests` (`test_cli.py`): a tearDown now clears
+  `SIPHRIX_NO_SIDE_EFFECTS` after tests that invoke
+  `--profile safe_defaults`.
+- **new `tests/test_packaging_surface.py`** — 15 tests pinning the
+  shipped contract without requiring a full `python -m build`:
+  pyproject metadata truthfulness (description / keywords / MIT
+  classifier / Python version classifiers / Homepage + Issues URLs /
+  `siphrix = siphrix.cli.app:main` entry point), public API
+  shape (`siphrix.__all__` vs expected 9-name set), shipped policy
+  pack + role overlay + canon YAMLs physically on disk next to the
+  installed package, `siphrix.cli.demo.main` importable, repo-only
+  subtrees (`siphrix.tests`, `siphrix.research`,
+  `siphrix.devtools.pytest_fallback`) excluded from the wheel by
+  the `[tool.setuptools.packages.find] exclude` list.
+- README Quickstart reorganised: step 2 is now the official
+  `siphrix demo` golden path (replaces the raw `python
+  examples/official_demo.py` form while still documenting the repo
+  entry point as an equivalent). New "What ships vs. what's
+  repo-only" table clarifies the installed surface.
+- Verified end-to-end by building the wheel, installing into a
+  clean venv, and exercising `siphrix --help`, `version`, `packs`,
+  `doctor`, `demo` — all succeed from the wheel install.
+
+### Product narrative & positioning consistency
+- Established **one canonical product tagline** used verbatim on
+  every first-impression surface:
+  "Siphrix — AI Action Firewall & Policy Runtime."
+- Aligned the five identity surfaces:
+    - `README.md` opening line (was: "A runtime enforcement engine
+      for AI agents.") + second identity restatement further down
+      (was: "canonical enforcement engine for AI systems").
+    - `siphrix/__init__.py` module docstring first line (was:
+      "deterministic runtime control layer for AI systems.").
+    - `SECURITY.md` opening paragraph — new "**Siphrix — AI Action
+      Firewall & Policy Runtime.**" lead preserves the existing
+      threat-model content verbatim.
+    - `pyproject.toml` `description` — unchanged (already aligned in
+      the packaging round).
+    - `siphrix` CLI top-level `--help` — unchanged (already aligned
+      in the CLI round).
+- Introduced explicit **supporting-layer vocabulary** so the one
+  external identity does not erase internal architecture detail:
+  *policy decision layer*, *runtime enforcement layer*,
+  *trust / audit / governance support layer*, *operator readiness
+  surface*. The README's "What Siphrix v1.0.0 Includes" section
+  now groups every existing feature bullet under one of the four
+  layers — no feature removed, no capability renamed, just a
+  reading-aid regrouping.
+- **new `tests/test_product_positioning.py`** — 8 narrow, robust
+  invariants: canonical tagline present at the head of README,
+  SECURITY, package docstring, pyproject description; CLI module
+  carries the product-positioning phrase; three historic identity
+  phrases ("runtime enforcement engine for AI", "deterministic
+  runtime control layer for AI", "canonical enforcement engine for
+  AI") are banned from the head of each identity surface; the four
+  supporting-layer labels remain legible somewhere in README; and
+  the three real installed commands (`siphrix doctor`,
+  `siphrix doctor --json`, `siphrix demo`) are documented in
+  README. The tests are **head-scoped** on each file: supporting-layer
+  vocabulary deeper in the docs remains legitimate architecture
+  language and is explicitly not policed.
+
+### Release workflow & three-gate release model
+- Introduced the canonical **three-gate release model** inside
+  `tools/release_check.py`, with named constants:
+    - `repo_ready` — repo healthy for development (members:
+      `doctor`, `version_consistency`).
+    - `package_ready` — package safe to publish (members:
+      `build_artifacts`, `wheel_contents`, `sdist_contents`,
+      `twine_check`, `install_smoke`).
+    - `production_posture_ready` — **informational** gate derived
+      from `siphrix doctor`'s `launch_readiness.production_ready`
+      bit. Not a publication blocker in the default exit-code
+      contract.
+- New PASS / WARN / FAIL banner (`_format_gate_banner`): lists each
+  gate with its verdict and per-gate blockers, ends with one
+  decision line (`OVERALL: PUBLISH OK` / `OVERALL: DO NOT PUBLISH`
+  / `OVERALL: BLOCKED (--strict-production)`) that operators and CI
+  can grep.
+- New `--strict-production` CLI flag — exit code `2` when repo and
+  package gates both PASS but production posture is not PASS. Useful
+  for release cuts that must land on a hardened install.
+- Legacy `--strict` flag preserved: promotes DEGRADED/SKIPPED in
+  the two publication gates to FAIL.
+- Exit-code contract documented: `0` = publish OK, `1` = repo or
+  package gate failed, `2` = `--strict-production` caught a
+  development-posture install.
+- JSON output (`--json`) carries a new `release_gates` section with
+  per-gate `verdict` + `blockers` + the final `exit_code`, so CI
+  jobs gate directly on a stable machine-readable shape.
+- **new `docs/release/RELEASE_RUNBOOK.md`** — the canonical live
+  release runbook. One page. Three-gate model explained. Preflight
+  checklist. One canonical release-gate command. Manual smoke
+  against the exact installed CLI surface (`siphrix version`,
+  `siphrix --help`, `siphrix doctor`, `siphrix doctor --json`,
+  `siphrix demo`). Publish + rollback steps.
+- `CONTRIBUTING.md` grows a short "Release flow" section pointing
+  at the runbook and naming the canonical gate command.
+- `docs/release/README.md` promotes the runbook to the canonical
+  (live) section.
+- README "Release Documents" list leads with the runbook.
+- **new `tests/test_release_gate_model.py`** — 22 invariants across
+  5 test classes: three gate constants exist; gate membership is a
+  partition of `SUBSYSTEM_IDS`; `production_posture_ready` is not a
+  subsystem id; gate verdict logic (PASS / WARN / FAIL + `--strict`
+  promotion); exit-code contract for all three documented cases
+  (publish OK, publish OK with production WARN, publish blocked,
+  `--strict-production` exit 2); banner shape; runbook + CONTRIBUTING
+  consistency (names the gates, references the canonical command,
+  lists every installed smoke command). Together these prove the
+  release model is machine-pinned and cannot silently drift.
+- Live end-to-end demonstrated against the current working tree
+  (repo_ready=PASS, package_ready=FAIL, production_posture_ready=WARN,
+  OVERALL=DO NOT PUBLISH, exit 1) — a pre-existing Windows
+  `install_smoke` path race, independent of this round's changes.
+- every repo-level test that previously wrote into `tests/.tmp/` now writes
+  under `tempfile.gettempdir()/siphrix/`; the executor-adapter tests use
+  the same tempfile root instead of a repo-local `tests_runtime/` directory
+
+### Packaging discipline
+- `pyproject.toml` explicitly excludes `siphrix.tests`, `siphrix.research`,
+  and `siphrix.devtools.pytest_fallback` from the installable wheel while
+  keeping them in the repository for CI
+- `MANIFEST.in` prunes the same subtrees from the sdist; wheel + sdist contents
+  audited post-build (748 / 1 129 entries, zero leakage of forbidden subtrees)
+- removed the repo-root `pytest/` shadow module that was shadowing the real
+  `pytest` package; the offline fallback remains only at
+  `siphrix/devtools/pytest_fallback/`
+
+### CI release gate
+- **new `.github/workflows/release-gate.yml`** — CI workflow that runs
+  `tools/release_check.py` on push/PR across Python 3.11 and 3.12, uses
+  `--strict` on `v*` tag pushes, uploads the built `dist/` only on tag
+  builds, and (when configured with a GitHub Environment) chains a
+  manually-approved `publish-pypi` job that uses PyPI Trusted Publishing
+  (OIDC) — no long-lived API tokens stored in the repository
+- `make release-check` — local equivalent of the CI job
+
+### Release artifact signing
+- **new `siphrix.release`** module with the canonical release-manifest
+  helpers (`build_release_manifest`, `sign_release_manifest`,
+  `write_release_manifest`, `load_release_manifest`,
+  `verify_release_manifest`). The signed manifest is canonical JSON over
+  every declared artifact's name, size, and SHA-256, signed once with
+  Ed25519 via `siphrix.foundation.proof_bundle` (no new crypto
+  primitive)
+- **new `tools/release_sign.py`** — operator script. Runs after
+  `python -m build` over a populated `dist/` directory and writes
+  `dist/release_manifest.json`. Private keys stay outside the repo via
+  the on-disk convention already owned by
+  `foundation.proof_bundle.ensure_keypair`
+- **new `tools/release_verify.py`** — consumer-side verifier. Re-hashes
+  every declared artifact and verifies the Ed25519 signature; exits
+  non-zero on any tamper
+- **new `tests/test_release_signing.py`** — 28 offline tests covering
+  digest correctness, manifest round-trip, tamper detection (wheel
+  bytes, sdist bytes, missing artifact, forged signature, edited
+  manifest field), deterministic verification, and end-to-end operator
+  flow
+
+### Operator dashboard (all 8 pages shipped, framework-free)
+- **new `docs/ui/DASHBOARD.md`** — canonical dashboard spec: page map,
+  component list, data contracts, UI states, explicit out-of-scope
+  list. The dashboard is a **read-only-or-ephemeral projection** of
+  existing product surfaces — no new backend, no framework, no npm
+- **new `tools/siphrix_dashboard/`** — the implementation. Stdlib-only
+  Python dev server + plain HTML + vanilla JS. Every `/api/*` endpoint
+  is a thin adapter over an already-shipped command or Python helper
+- **v1 pages** (read-only projections): **Overview**, **Readiness**,
+  **Policy Packs**, **Release State** — each binds to
+  `siphrix doctor --json`, `siphrix.policy_packs.list_policy_packs()`,
+  and `python tools/release_check.py --json`
+- **v2 pages** (ephemeral endpoints with bounded input contracts):
+  **Audit** (read-only view of the canonical events log, pinned to
+  `runtime_paths.events_log_path()`; closed-vocabulary chip filter,
+  not a filesystem browser); **Policy Check** (one textarea → one
+  `PolicyManager.decide()` call gated by `PolicyInput.from_dict()`;
+  64 KB body cap, never writes); **Demo** (one button shelling out to
+  the canonical `siphrix demo` CLI with a 30 s timeout and a 256 KB
+  per-stream cap; not a terminal emulator); **Runtime** (one textarea →
+  one `run_pipeline()` call in-process; 16 KB input cap; does **not**
+  call `RuntimeConfig.apply()`, so no env vars leak into the dev
+  server process)
+- Six read-only GET endpoints (`/api/doctor`, `/api/packs`,
+  `/api/release`, `/api/runtime-paths`, `/api/version`, `/api/audit`) +
+  three ephemeral POST endpoints (`/api/policy-check`, `/api/demo`,
+  `/api/runtime-run`), all documented at `docs/ui/DASHBOARD.md` §5.
+  Every POST envelope carries a uniform `{status, error, …}` shape so
+  UI code can assume the key set
+- **new `tests/test_dashboard_shell.py`** — ~115 tests across 13
+  classes pinning file layout, nav wiring, shared-asset references,
+  endpoint shapes + live smoke, no-write-path invariants, scope
+  guarantees (no arbitrary command / file-path / profile knobs on any
+  POST endpoint), and cross-page consistency invariants
+- **new `tests/test_ui_dashboard_spec.py`** — 29 tests pinning the
+  spec structure, data-contract grounding, framework-free stance, and
+  showcase-readiness pointers
+
+### Showcase + public handoff
+- **new `docs/ui/SHOWCASE.md`** — 5-minute operator tour covering
+  version / doctor → demo → dashboard → release gate. Every command,
+  file path, and return shape is the one shipping today
+- README Quickstart grows a dashboard-launch step and a direct
+  pointer to `docs/ui/SHOWCASE.md`
+- `docs/ui/README.md` rewritten to reflect the shipped 8-page reality;
+  historical "v1 shell" / "reserved stubs" framing removed
+- `tools/siphrix_dashboard/README.md` drops per-page "Xth
+  implemented v2 page" narrative; all pages read as one grouped set
+- `docs/release/README.md` + `docs/README.md` indexes updated to
+  reference the Showcase doc and the CI release-gate workflow
+
+## v1.0.0
+
+### Core product
+- established the canonical non-versioned `siphrix` product surface
+- absorbed historical feature tracks into the active package tree
+- hardened runtime, trust, governance, resilience, analysis, and testing paths
+- added the canonical kernel syscall interception layer
+- added distribution channel foundation and policy versioning architecture
+- completed Stage 2.1 ultra hardening across all modules
+
+### Packaging and release metadata
+- added `MANIFEST.in` and `[project.urls]` for release-grade packaging
+- aligned version string across `README`, `CHANGELOG`, `pyproject.toml`, and `__init__.py`
+- added root-level `.gitignore` protecting `.venv/`, `.claude/`, cache / build artefacts
+- added `SECURITY.md` and `CONTRIBUTING.md`
+- added GitHub Actions CI with smoke (3.11 / 3.12), structural invariants, and coverage jobs
+
+### Structural cleanup
+- removed three empty / dead directories (`state/`, `tests_runtime/` scaffold, `siphrix/framework/`)
+- removed root-level `integration_snapshot.py` and `planner_contract.py` compatibility shims
+- removed duplicate root-level `planners/` directory; the canonical location is `siphrix.adapters.planners`
+- merged canonical builder functions from `siphrix/examples/` into the root-level integration scripts
+- migrated 23 imports to canonical paths (`siphrix.contracts.planner`, `siphrix.adapters.planners.*`)
+
+### API surface
+- replaced wildcard `__init__.py` re-exports in `siphrix.governance` and
+  `siphrix.policy_versioning` with 454 and 1137 explicitly enumerated public symbols
+- added `test_public_api_surface` and `test_repo_structure_invariants` to lock in the
+  explicit export contract
+
+### Internal hardening
+- replaced the Canon DSL `eval()` call with an AST-whitelisted evaluator that
+  rejects function calls, subscripts, arithmetic, lambdas, and comprehensions
+  before any value is read
+- added defence-in-depth limits to the shell executor: 512-character command
+  length cap, 16-argument cap, 10-second subprocess timeout, null byte and
+  newline rejection
+- added a transport scheme allowlist (`http` / `https`) and a 16 MiB response
+  body cap to the `http_get` choke point, both enforced before policy
+  evaluation runs
+- added hardening test suites for the three boundaries above

siphrix-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,191 @@
+# Contributing to Siphrix
+
+Thank you for taking the time to contribute.  Siphrix is a small,
+focused codebase; keeping it that way is the point.  This document
+describes how to set up your environment, run the tests, and make
+changes that do not regress the guarantees the project already provides.
+
+## Development environment
+
+Requirements:
+- Python 3.11 or newer (CI covers 3.11 and 3.12)
+- `git`
+
+Set up:
+
+```bash
+git clone <repo-url>
+cd siphrix   # the product root (contains pyproject.toml)
+python -m venv .venv
+# macOS / Linux
+source .venv/bin/activate
+# Windows PowerShell
+.\.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+```
+
+## Running the tests
+
+From the `siphrix/` product root:
+
+```bash
+# Fast path — compile + focused hardening tests (~2 seconds)
+python -m compileall -q siphrix
+python -m unittest tests.test_public_api_surface
+python -m unittest tests.test_canon_runtime_hardening
+python -m unittest tests.test_shell_executor_hardening
+python -m unittest tests.test_intercept_http_hardening
+python -m unittest tests.test_repo_structure_invariants
+
+# Full repo-level unit suite
+python -m unittest discover -s tests -q
+
+# Package-internal public-API suite (2353 tests, repo-only — not shipped in the wheel)
+python -m unittest discover -s siphrix/tests -t .
+
+# Canonical smoke runner
+python -m siphrix.tests_all_global
+
+# Interactive demo
+python examples/app.py
+
+# Practical integration examples
+python examples/example_agent.py --list-scenarios
+python examples/example_agent.py --scenario blocked_delete
+```
+
+Coverage (optional):
+
+```bash
+pip install coverage
+coverage run -m unittest discover -s tests -q
+coverage report --skip-covered --precision=1
+```
+
+## Adding a new Canon law
+
+Canon laws live in `siphrix/canon/canon_v1_laws.yaml`.  Each law has a
+trigger expression written in the Canon DSL.
+
+Rules:
+
+1. Keep the DSL grammar: boolean operators (`AND`, `OR`), comparison
+   operators (`==`, `!=`, `<`, `>`, `<=`, `>=`), membership (`IN`,
+   `NOT_IN`), literals (`true`, `false`, `null`, numbers, quoted
+   strings, list literals), bare names, dotted references,
+   parentheses.  **No** function calls, subscripts, arithmetic.
+2. Avoid attribute names that are Python reserved words
+   (`class`, `def`, `import`, ...).  The AST parser will silently
+   treat the law as never triggered — there is no way around that
+   without changing the DSL grammar.
+3. Validate the law before committing:
+
+   ```python
+   from siphrix.canon.canon_runtime import CanonRuleEngine
+   CanonRuleEngine.validate_law_expression(my_expression)
+   ```
+
+4. Every new law should get at least one corresponding test in
+   `tests/` (or an entry in `siphrix/canon/conformance_tests.yaml`).
+
+## Changing the public API
+
+Every canonical package (`siphrix.governance`, `siphrix.policy_versioning`,
+etc.) publishes an explicit `__all__`.  The public surface is covered by
+`tests/test_public_api_surface.py`.
+
+Rules:
+
+1. **Do not** remove or rename a symbol without a deprecation path.
+2. **Do not** re-introduce wildcard imports in `__init__.py` files;
+   the explicit list is auditable and IDE-friendly.
+3. When adding a new public symbol:
+   - add it to the right `_public_api.py` (for `contracts`,
+     `console`, `constitution`, `constitution/execution`,
+     `constitution/execution/operational`, `governance`,
+     `policy_versioning`) or the relevant `__init__.py`
+     for packages whose root is the authoritative surface;
+   - include it in `__all__`;
+   - document any non-obvious contract.
+4. When removing internal helpers, confirm that no other module or
+   test imports them: `grep -r "from siphrix.x import y"`.
+
+## Adding or modifying an executor / adapter
+
+Adapters live under `siphrix/adapters/`.  The shell executor, HTTP
+interception choke point, and URL scheme allowlist have dedicated
+hardening suites — any change there must keep those tests green.
+
+Hard rules:
+
+- `subprocess.run` is called with `shell=False`.  Never change that.
+- The shell command allowlist is *intentionally* tiny.  Widening it
+  needs explicit justification in the PR description.
+- `http_get` enforces the transport allowlist **before** policy
+  evaluation.  Do not swap the order.
+
+## Style and consistency
+
+- Python module and directory names use `lowercase_with_underscores`.
+- Test files follow `test_<feature>[_foundation|closure|hardening].py`.
+- Examples / integration scripts at the project root use absolute
+  package paths (`from siphrix.X import Y`) unless they are importing
+  a local sibling module.
+- Keep functions small, docstrings short, and comments focused on *why*
+  (not *what*).
+
+## Commit and PR discipline
+
+1. One logical change per PR.
+2. Run the fast-path tests before pushing.
+3. Update `CHANGELOG.md` only when you add, remove, or change behaviour
+   that matters to downstream users.
+4. If your change touches the security posture (canon DSL, shell
+   executor, HTTP interception, crypto, trust), update `SECURITY.md`
+   in the same PR and add or update a hardening test.
+
+## Filing issues
+
+- **Bugs**: include a minimal reproduction and the full traceback.
+- **Feature requests**: explain the use case and the alternative
+  workflows you considered.
+- **Security**: follow `SECURITY.md` — do not open public issues.
+
+## Release flow
+
+When it is time to cut a release, follow
+[`docs/release/RELEASE_RUNBOOK.md`](docs/release/RELEASE_RUNBOOK.md).
+The release model is three named gates — `repo_ready`,
+`package_ready`, `production_posture_ready` — evaluated by the one
+canonical gate:
+
+```bash
+python tools/release_check.py
+```
+
+Do not invent a parallel release path. If a step you need is missing
+from the runbook, add it to the runbook.
+
+## Automated release gate (CI)
+
+CI runs the same command as local release validation:
+
+    python tools/release_check.py
+
+Behavior:
+- push / PR → default gate
+- tag (v*) → strict gate (--strict) → publish to TestPyPI → publish to PyPI
+
+On a `v*` tag push the workflow runs three jobs in order:
+`release-readiness` → `publish-testpypi` → `publish-pypi`. PyPI is
+gated on the `pypi` GitHub Environment, which requires reviewer
+approval (configured in repo Settings → Environments). Publish uses
+**PyPI Trusted Publishing (OIDC)** via `pypa/gh-action-pypi-publish`
+— no long-lived tokens in repository secrets.
+
+CI does NOT use `--strict-production`.
+Production posture is a deployment decision.
+
+See [`docs/release/RELEASE_RUNBOOK.md`](docs/release/RELEASE_RUNBOOK.md)
+for the first-time publish setup and the end-to-end tag-push flow.

siphrix-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Ghengeaua
+
+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.