resultseal 0.1.1__tar.gz

resultseal-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: A decision, classification, or report that contradicts the specifications
+labels: bug
+---
+
+**What happened**
+
+State the observed decision (`sealed` / `blocked`), truth state, and reason codes, and what the specifications in [docs/specs/](../blob/master/docs/specs/) require instead.
+
+**Minimal reproduction**
+
+The smallest contract plus input (or fixture) that produces it:
+
+```
+<paste YAML/JSON, CLI command, or fixture here>
+```
+
+**Expected behavior**
+
+What the promotion rules should have produced, citing `docs/specs/PROMOTION_RULES.md` where applicable.
+
+**Environment**
+
+- OS:
+- Python version:
+- resultseal version:

resultseal-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: A capability within ResultSeal's scope
+labels: enhancement
+---
+
+**Problem to solve**
+
+What observation-integrity failure mode or workflow does this address? Check [docs/specs/NON_GOALS.md](../blob/master/docs/specs/NON_GOALS.md) first — agent frameworks, proxies, dashboards, policy engines, retry middleware, signed receipts, and LLM judges are out of scope.
+
+**Proposed behavior**
+
+What should the new capability do, and how does it fit the existing contract → normalize → evaluate pipeline?
+
+**Determinism impact**
+
+Confirm the feature keeps decisions byte-deterministic given identical inputs and a pinned reference clock, and justify any new dependency.

resultseal-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,31 @@
+## What
+
+One line describing the change.
+
+## Failure mode addressed
+
+Link the issue, or state the failure mode: what was promoted, blocked, classified, or reported incorrectly?
+
+## Tests
+
+- [ ] Regression test or fixture included
+
+## Determinism
+
+- [ ] Decisions stay deterministic given identical inputs and a pinned reference clock
+- [ ] Reports and fingerprints carry no wall-clock values
+
+## Gates
+
+Exact results from the documented commands:
+
+```
+ruff check src tests:
+mypy src:
+pytest:
+```
+
+## Docs
+
+- [ ] Relevant specs under `docs/specs/` updated if behavior changed
+- [ ] `docs/decision-log.md` entry added if a documented invariant changed

resultseal-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m pytest -q
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Clean-install smoke
+        run: |
+          python -m pip install dist/*.whl
+          resultseal version
+          resultseal replay fixtures/empty-result.yaml

resultseal-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m pytest -q
+      - name: Lint
+        run: ruff check .
+      - name: Type check
+        run: mypy src
+
+  build:
+    runs-on: ubuntu-latest
+    needs: gate
+    environment: pypi
+    permissions:
+      # Required for trusted publishing to PyPI and creating the release.
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install build twine
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+      - name: Clean-install smoke (install the exact artifact, run it)
+        run: |
+          python -m venv /tmp/smoke-venv
+          /tmp/smoke-venv/bin/pip install dist/*.whl
+          /tmp/smoke-venv/bin/resultseal version
+          /tmp/smoke-venv/bin/resultseal replay fixtures/empty-result.yaml
+      - name: Publish to PyPI via trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: Create GitHub release with artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          body: See CHANGELOG.md for the release notes.

resultseal-0.1.1/.gitignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+.env
+.DS_Store
+
+resultseal_claude_code_handoff/
+
+# --- Local-only working documents -----------------------------------------
+# Internal planning, AI-workflow, and session-state files. They stay on the
+# maintainer's machine and are deliberately excluded from the public
+# repository (decision log D17).
+/ACCEPTANCE_CHECKLIST.md
+/CLAUDE.md
+/CLAUDE_CODE_HANDOFF.md
+/GITHUB_DISCOVERY_PLAYBOOK.md
+/IMPLEMENTATION_ORDER.md
+/IMPLEMENTATION_STATUS.md
+/MANIFEST.txt
+/MASTER_BUILD_PROMPT.md
+/PROBLEM_AND_RESEARCH.md
+/RELEASE_PLAN.md
+/RESEARCH_*
+/STATESEAL_CHAT_HANDOFF.md
+/TEST_STRATEGY.md
+/prompts/
+/docs/superpowers/
+/docs/test-evidence.md
+/docs/requirements-matrix.md

resultseal-0.1.1/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+## 0.1.1 — 2026-08-23
+
+### Fixed
+
+- Shipped examples now work end to end: `examples/http_empty.json` carries
+  its body under the field name the HTTP adapter actually hashes (`body`,
+  previously the unread `response_body`, so the envelope hashed null);
+  `examples/mcp_result.json` gained the `source_ref`/`target_ref` identity
+  fields every adapter input requires; and new
+  `examples/customer_contract.json` makes both runnable through
+  `resultseal check`. Example validation no longer skips raw-response
+  shapes — each must normalize into an envelope satisfying
+  `schemas/observation-envelope.v1.json` (D21).
+
+### Added
+
+- Tag-driven publish workflow: a `v*` tag runs the full gate suite,
+  builds and smoke-installs the wheel, then uploads to PyPI via trusted
+  publishing and attaches artifacts to a GitHub Release.
+- A naive-but-parseable `observed_at` under `max_age_seconds` freshness
+  now blocks as `unknown`/`SCHEMA_INVALID` instead of escaping `evaluate`
+  as an unclassified `TypeError` (D18).
+- `resultseal replay --format json --redact` now redacts before
+  fingerprinting, matching `resultseal check`, so the printed
+  `deterministic_fingerprint` verifies against the printed record.
+  Redacted replay output differs byte-wise from 0.1.0; unredacted output
+  is unchanged (D19).
+
+### Changed
+
+- Internal readability cleanups with no behavior change: shared
+  expectation-matching and record-pipeline helpers, single homes for
+  `format_clock` and the fingerprint key, unused parameters removed (D20).
+
+## 0.1.0 — 2026-08-22 (public alpha)
+
+First implementation release. Offline, deterministic observation-integrity
+gate for AI-agent tool results.
+
+### Added
+
+- Typed, frozen observation envelope and contract models with strict
+  construction (`models.py`); stable error taxonomy mapping failures to
+  public reason codes and CLI exit codes (`errors.py`).
+- Canonical JSON serialization, `content_hash`, and self-excluding decision
+  fingerprints (`canonical.py`).
+- Pure promotion rules engine with documented precedence, natural-order
+  source-version comparison, and injected clock (`rules.py`).
+- Bounded safe input loading: size/depth/node/string limits before parse;
+  YAML restricted to an explicit tag allowlist with anchors/aliases rejected;
+  path containment helpers (`limits.py`, `safeio.py`).
+- Contract and self-contained fixture loaders (`contracts.py`,
+  `fixtures.py`); shipped fixtures embed their contracts inline.
+- HTTP/JSON, MCP-style, and stdio normalizers establishing structural facts
+  only (`normalize.py`).
+- CLI: `resultseal version | validate | check | replay` with stable exit
+  codes (0/1/2/3) and deterministic JSON or Markdown reports (`cli.py`,
+  `report.py`).
+- Reason-code `PROTOCOL_CONFLICT` for self-contradicting protocol results
+  (e.g. MCP `isError: true` alongside success-shaped content), added per the
+  ERROR_CODES extension process.
+- Contract schema v1 gains optional `min_source_version` (additive D8).
+
+### Guarantee scope
+
+Deterministic given identical inputs and a pinned reference clock. Reports
+and fingerprints never contain wall-clock values. Max-age freshness uses the
+injected clock only. See docs/specs/THREAT_MODEL.md for the security boundary: this
+tool protects the local promotion decision, not external systems.

resultseal-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+# Code of Conduct
+
+Participants must be respectful, constructive, and focused on improving the software. Harassment, discrimination, doxxing, malicious reports, and hostile behavior are not welcome. Maintainers may remove content or participation that violates these expectations.
+

resultseal-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Contributing
+
+Keep changes narrow and evidence-driven. A contribution should state the failure mode it addresses, include a regression test or fixture, preserve determinism, and update relevant protocol or CLI documentation. New adapters must not convert transport success into semantic success. Do not add network access, dynamic execution, or hidden model calls.
+
+A change that touches a documented invariant — a promotion rule, an error code, a schema field, an adapter behavior — adds a new dated entry to [docs/decision-log.md](docs/decision-log.md): a `## D<number> — <date> — <title>` heading after the last entry, followed by a concise statement of what was decided and why, in the style of the existing entries. The log is append-only; a superseded decision is corrected by a newer entry, never by rewriting an old one.
+
+Before opening a pull request, run the documented test, lint, type, and build commands. Include exact results and explain any platform-specific behavior.
+

resultseal-0.1.1/LICENSE

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

resultseal-0.1.1/Makefile

@@ -0,0 +1,22 @@
+.PHONY: install test lint typecheck build demo all
+
+install:
+	python -m pip install -e ".[dev]"
+
+test:
+	python -m pytest -q
+
+lint:
+	ruff check .
+
+typecheck:
+	mypy src
+
+build:
+	python -m build || uv build
+
+demo:
+	resultseal replay fixtures/empty-result.yaml
+	resultseal replay fixtures/explicit-not-found.yaml
+
+all: test lint typecheck build

resultseal-0.1.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: resultseal
+Version: 0.1.1
+Summary: Deterministic observation-integrity contracts for AI-agent tool results
+Author: ResultSeal contributors
+License: MIT License
+        
+        Copyright (c) 2026 ResultSeal contributors
+        
+        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.
+License-File: LICENSE
+Keywords: ai-agents,contract-testing,determinism,llm,mcp,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: pyyaml<7,>=6
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: jsonschema<5,>=4; extra == 'dev'
+Requires-Dist: mypy<2,>=1.13; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ResultSeal
+
+[![CI](https://github.com/sx4im/resultseal/actions/workflows/ci.yml/badge.svg)](https://github.com/sx4im/resultseal/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+
+**HTTP 200 is not an observation. Empty is not not-found. A tool call is not an effect.**
+
+ResultSeal is a small, framework-neutral Python toolkit that prevents AI-agent workflows from promoting empty, partial, stale, source-mismatched, or unverified tool results into factual claims. Shipped adapters cover raw JSON, HTTP responses, MCP-style tool results (`structuredContent` / `isError` / `outputSchema`), and stdio process output — each establishing structural facts only (see [docs/specs/ADAPTERS.md](docs/specs/ADAPTERS.md)).
+
+## What it does
+
+ResultSeal normalizes a tool result, applies a declarative contract, and produces a deterministic decision. Unknown and incomplete evidence is blocked by default.
+
+## Install
+
+Not on PyPI yet — install from a clone:
+
+```bash
+git clone https://github.com/sx4im/resultseal.git
+cd resultseal
+pip install .
+```
+
+Requires Python 3.11+.
+
+## Try it
+
+```bash
+# Replay a self-contained fixture bundle against its recorded expectation
+resultseal replay fixtures/empty-result.yaml         # empty response -> blocked/empty
+resultseal replay fixtures/explicit-not-found.yaml   # approved sentinel -> sealed/not_found
+
+# Evaluate a shipped example against a shipped contract (exit 0 = sealed, 1 = blocked)
+resultseal check examples/mcp_result.json --contract examples/customer_contract.json
+resultseal check examples/http_empty.json --contract examples/customer_contract.json
+```
+
+The last two are the toolkit's thesis side by side: a complete MCP result seals,
+while an HTTP 200 carrying an empty body blocks as `empty` — it can never be
+promoted to `not_found`. All four commands print the decision record with a
+verifiable `deterministic_fingerprint`.
+
+## Scope
+
+ResultSeal is not an agent framework, proxy, dashboard, policy engine, retry middleware, signed receipt system, or LLM judge. It is an executable semantic boundary for tool observations.
+
+## Development
+
+```bash
+make install   # editable install with dev tools
+make all       # test, lint, typecheck, build
+```
+
+## Contributing
+
+Bug reports, fixes, and spec feedback are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for what a change is expected to include. The normative specifications live in [docs/specs/](docs/specs/), and changes that touch a documented invariant add a dated entry to the [decision log](docs/decision-log.md).

resultseal-0.1.1/README.md

@@ -0,0 +1,57 @@
+# ResultSeal
+
+[![CI](https://github.com/sx4im/resultseal/actions/workflows/ci.yml/badge.svg)](https://github.com/sx4im/resultseal/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+
+**HTTP 200 is not an observation. Empty is not not-found. A tool call is not an effect.**
+
+ResultSeal is a small, framework-neutral Python toolkit that prevents AI-agent workflows from promoting empty, partial, stale, source-mismatched, or unverified tool results into factual claims. Shipped adapters cover raw JSON, HTTP responses, MCP-style tool results (`structuredContent` / `isError` / `outputSchema`), and stdio process output — each establishing structural facts only (see [docs/specs/ADAPTERS.md](docs/specs/ADAPTERS.md)).
+
+## What it does
+
+ResultSeal normalizes a tool result, applies a declarative contract, and produces a deterministic decision. Unknown and incomplete evidence is blocked by default.
+
+## Install
+
+Not on PyPI yet — install from a clone:
+
+```bash
+git clone https://github.com/sx4im/resultseal.git
+cd resultseal
+pip install .
+```
+
+Requires Python 3.11+.
+
+## Try it
+
+```bash
+# Replay a self-contained fixture bundle against its recorded expectation
+resultseal replay fixtures/empty-result.yaml         # empty response -> blocked/empty
+resultseal replay fixtures/explicit-not-found.yaml   # approved sentinel -> sealed/not_found
+
+# Evaluate a shipped example against a shipped contract (exit 0 = sealed, 1 = blocked)
+resultseal check examples/mcp_result.json --contract examples/customer_contract.json
+resultseal check examples/http_empty.json --contract examples/customer_contract.json
+```
+
+The last two are the toolkit's thesis side by side: a complete MCP result seals,
+while an HTTP 200 carrying an empty body blocks as `empty` — it can never be
+promoted to `not_found`. All four commands print the decision record with a
+verifiable `deterministic_fingerprint`.
+
+## Scope
+
+ResultSeal is not an agent framework, proxy, dashboard, policy engine, retry middleware, signed receipt system, or LLM judge. It is an executable semantic boundary for tool observations.
+
+## Development
+
+```bash
+make install   # editable install with dev tools
+make all       # test, lint, typecheck, build
+```
+
+## Contributing
+
+Bug reports, fixes, and spec feedback are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for what a change is expected to include. The normative specifications live in [docs/specs/](docs/specs/), and changes that touch a documented invariant add a dated entry to the [decision log](docs/decision-log.md).

resultseal-0.1.1/ROADMAP.md

@@ -0,0 +1,14 @@
+# Roadmap
+
+## Public alpha
+
+The public alpha is the offline deterministic core: envelope models, promotion rules, safe fixture loading, three normalizers, CLI, reports, tests, and CI.
+
+## Later, only with user evidence
+
+Possible follow-up work includes more adapters, a plugin protocol, optional cryptographic evidence references, and integrations with existing test frameworks. These are not part of the MVP and must not be added until the core semantics are stable and users request them.
+
+## Forbidden expansion
+
+Do not expand into a hosted service, general agent runtime, dashboard, policy engine, transaction manager, or universal evaluator.
+

resultseal-0.1.1/SECURITY.md

@@ -0,0 +1,6 @@
+# Security Policy
+
+ResultSeal is designed to process untrusted result data locally. Do not put production secrets in fixtures or issue reports. Report a vulnerability privately through the repository’s configured security contact rather than opening a public issue with exploit details.
+
+Security-critical behavior includes safe parsing, bounded inputs, path containment, no dynamic execution, no network access, redaction, deterministic decisions, and fail-closed promotion. Security fixes require a regression test and a changelog entry.
+