stipulate 0.1.0__tar.gz

stipulate-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include uv.lock
+recursive-include docs *.md *.json
+recursive-include tools *.py *.json
+recursive-include tests *.py

stipulate-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: stipulate
+Version: 0.1.0
+Summary: Contracts for Python interfaces
+Author: Stipulate contributors
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typing_extensions>=4.15.0
+Provides-Extra: dev
+Requires-Dist: pytest==8.4.2; extra == "dev"
+Requires-Dist: hypothesis==6.140.3; extra == "dev"
+Requires-Dist: ruff==0.13.2; extra == "dev"
+Requires-Dist: pyright==1.1.411; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: build==1.3.0; extra == "dev"
+Requires-Dist: twine==6.2.0; extra == "dev"
+
+# Stipulate
+
+**Contracts for Python interfaces.**
+
+**Define. Validate. Evolve.**
+
+Stipulate checks dynamically supplied implementations against Python structural interfaces, explains mismatches, and preserves what available metadata cannot establish.
+
+## Status
+
+This repository contains the Stipulate 0.1 implementation, design specification, and design probes. The core API checks declared Protocol compatibility without executing candidate operations. Earlier prototypes are historical inputs, not release evidence.
+
+Install with `python -m pip install .` (CPython 3.11–3.14). See the [implemented feature guide](docs/IMPLEMENTED_0_1.md) for the supported boundary. Independent Sol review is still required before release approval.
+
+## Define and validate
+
+```python
+from typing import Protocol
+from stipulate import Contract
+
+
+class Storage(Protocol):
+    def read(self, key: str) -> bytes | None: ...
+
+    async def write(self, key: str, value: bytes) -> None: ...
+
+
+class MemoryStorage:
+    def __init__(self) -> None:
+        self._items: dict[str, bytes] = {}
+
+    def read(self, key: str) -> bytes | None:
+        return self._items.get(key)
+
+    async def write(self, key: str, value: bytes) -> None:
+        self._items[key] = value
+
+
+candidate = MemoryStorage()
+storage_contract = Contract(Storage)
+storage = storage_contract.validate(candidate)
+```
+
+Implementations are ordinary Python classes. They need no inheritance, registration, or decorators. Validation returns the original object, typed as `Storage`, after checking its available declarations against the contract. The constructor uses TypeForm for inference; the [typing guide](docs/STATIC_TYPING.md) records supported checker settings, including the current mypy feature flag.
+
+Strict validation is the default: incompatible or insufficient evidence raises `ContractError`. To allow missing implementation type annotations deliberately, use `strict=False`; known mismatches and unsupported or uninspectable candidate capabilities still fail. Invalid requirements fail contract construction.
+
+## Understand a result
+
+```python
+result = storage_contract.check(candidate)
+print(result)
+
+if result:
+    print("Storage declarations are compatible")
+
+result.status
+result.complete
+result.errors()
+result.unknowns()
+result.evidence
+```
+
+`check()` reports candidate mismatches without raising `ContractError`. Truthiness means compatibility was established for every requirement; unknown evidence is false. Invalid contract definitions raise `ContractDefinitionError`. The result includes locations, reasons, and suggested fixes.
+
+Stipulate compares signatures, annotation assignability, binding, and supported member capabilities. It assumes implementations honor their declarations; it does not execute methods to verify their behavior, validate future return values, or prevent later mutation. Annotation resolution may execute Python annotation expressions in the default trusted mode.
+
+## Friendly errors
+
+```text
+Incompatible with Storage
+2 incompatible findings; 0 unknown findings (0 blocked obligations).
+
+read.key
+  The implementation input is too narrow for required caller values
+  Required: str
+  Provided: bytes
+  [parameter_type; incompatible]
+
+write.kind
+  The coroutine execution kind differs
+  [async_mismatch; incompatible]
+```
+
+## Interface shorthand — experimental design target
+
+```python
+from stipulate import Interface
+
+class Storage(Interface):
+    def read(self, key: str) -> bytes | None: ...
+
+storage = Storage.validate(candidate)
+```
+
+This shorthand is not a 0.1 promise. It must preserve structural typing, precise class-side methods, inheritance, and clean protocol members in installed-package Pyright/mypy tests before promotion. The supported 0.1 plan uses `Protocol` plus `Contract`, with the same method-based operations and compatibility engine.
+
+## Evolution and tooling — later releases
+
+```python
+report = Contract(StorageV1).compare(Contract(StorageV2))
+schema = storage_contract.schema()
+fingerprint = storage_contract.fingerprint()
+```
+
+Comparison will report implementer and consumer compatibility separately. Unknown results cannot certify a non-breaking change. Schemas and fingerprints will be versioned before publication. None of these three operations is in the 0.1 public surface.
+
+## Documentation
+
+Start with the [quickstart](docs/QUICKSTART.md). The [experience design](docs/EXPERIENCE_DESIGN.md) specifies the API journey, readable reports, and usability bar.
+
+- [Product Vision](docs/PRODUCT_VISION.md)
+- [Public Interface Model](docs/INTERFACE_MODEL.md)
+- [Contract Engine](docs/CONTRACT_ENGINE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Type System](docs/TYPE_SYSTEM.md)
+- [Validation Engine](docs/VALIDATION_ENGINE.md)
+- [Static Typing](docs/STATIC_TYPING.md)
+- [Errors](docs/ERROR_MODEL.md)
+- [Performance and Caching](docs/PERFORMANCE.md)
+- [Testing](docs/TESTING_STRATEGY.md)
+- [Compatibility](docs/COMPATIBILITY.md)
+- [Dependencies](docs/DEPENDENCIES.md)
+- [Competition](docs/COMPETITION.md)
+- [Pydantic Integration](docs/PYDANTIC_INTEGRATION.md)
+- [Roadmap and 0.x release phases](docs/ROADMAP.md)
+- [Release and PyPI trusted publishing](docs/RELEASING.md)
+- [Design Decisions](docs/DESIGN_DECISIONS.md)
+- [Implementation Plan](docs/IMPLEMENTATION_PLAN.md)
+- [Phase 0.1 implementation contract](docs/PHASE_0_1_IMPLEMENTATION_CONTRACT.md)
+- [Open Technical Problems](docs/OPEN_TECHNICAL_PROBLEMS.md)
+- [Design probes](design_probes/README.md)
+
+The roadmap owns release scope; design decisions own durable policy; focused specifications own behavior; the open-problem register owns implementation evidence and unresolved acceptance work. Contradictions must be reconciled in the same change. A decision does not count as a tested implementation.

stipulate-0.1.0/README.md

@@ -0,0 +1,134 @@
+# Stipulate
+
+**Contracts for Python interfaces.**
+
+**Define. Validate. Evolve.**
+
+Stipulate checks dynamically supplied implementations against Python structural interfaces, explains mismatches, and preserves what available metadata cannot establish.
+
+## Status
+
+This repository contains the Stipulate 0.1 implementation, design specification, and design probes. The core API checks declared Protocol compatibility without executing candidate operations. Earlier prototypes are historical inputs, not release evidence.
+
+Install with `python -m pip install .` (CPython 3.11–3.14). See the [implemented feature guide](docs/IMPLEMENTED_0_1.md) for the supported boundary. Independent Sol review is still required before release approval.
+
+## Define and validate
+
+```python
+from typing import Protocol
+from stipulate import Contract
+
+
+class Storage(Protocol):
+    def read(self, key: str) -> bytes | None: ...
+
+    async def write(self, key: str, value: bytes) -> None: ...
+
+
+class MemoryStorage:
+    def __init__(self) -> None:
+        self._items: dict[str, bytes] = {}
+
+    def read(self, key: str) -> bytes | None:
+        return self._items.get(key)
+
+    async def write(self, key: str, value: bytes) -> None:
+        self._items[key] = value
+
+
+candidate = MemoryStorage()
+storage_contract = Contract(Storage)
+storage = storage_contract.validate(candidate)
+```
+
+Implementations are ordinary Python classes. They need no inheritance, registration, or decorators. Validation returns the original object, typed as `Storage`, after checking its available declarations against the contract. The constructor uses TypeForm for inference; the [typing guide](docs/STATIC_TYPING.md) records supported checker settings, including the current mypy feature flag.
+
+Strict validation is the default: incompatible or insufficient evidence raises `ContractError`. To allow missing implementation type annotations deliberately, use `strict=False`; known mismatches and unsupported or uninspectable candidate capabilities still fail. Invalid requirements fail contract construction.
+
+## Understand a result
+
+```python
+result = storage_contract.check(candidate)
+print(result)
+
+if result:
+    print("Storage declarations are compatible")
+
+result.status
+result.complete
+result.errors()
+result.unknowns()
+result.evidence
+```
+
+`check()` reports candidate mismatches without raising `ContractError`. Truthiness means compatibility was established for every requirement; unknown evidence is false. Invalid contract definitions raise `ContractDefinitionError`. The result includes locations, reasons, and suggested fixes.
+
+Stipulate compares signatures, annotation assignability, binding, and supported member capabilities. It assumes implementations honor their declarations; it does not execute methods to verify their behavior, validate future return values, or prevent later mutation. Annotation resolution may execute Python annotation expressions in the default trusted mode.
+
+## Friendly errors
+
+```text
+Incompatible with Storage
+2 incompatible findings; 0 unknown findings (0 blocked obligations).
+
+read.key
+  The implementation input is too narrow for required caller values
+  Required: str
+  Provided: bytes
+  [parameter_type; incompatible]
+
+write.kind
+  The coroutine execution kind differs
+  [async_mismatch; incompatible]
+```
+
+## Interface shorthand — experimental design target
+
+```python
+from stipulate import Interface
+
+class Storage(Interface):
+    def read(self, key: str) -> bytes | None: ...
+
+storage = Storage.validate(candidate)
+```
+
+This shorthand is not a 0.1 promise. It must preserve structural typing, precise class-side methods, inheritance, and clean protocol members in installed-package Pyright/mypy tests before promotion. The supported 0.1 plan uses `Protocol` plus `Contract`, with the same method-based operations and compatibility engine.
+
+## Evolution and tooling — later releases
+
+```python
+report = Contract(StorageV1).compare(Contract(StorageV2))
+schema = storage_contract.schema()
+fingerprint = storage_contract.fingerprint()
+```
+
+Comparison will report implementer and consumer compatibility separately. Unknown results cannot certify a non-breaking change. Schemas and fingerprints will be versioned before publication. None of these three operations is in the 0.1 public surface.
+
+## Documentation
+
+Start with the [quickstart](docs/QUICKSTART.md). The [experience design](docs/EXPERIENCE_DESIGN.md) specifies the API journey, readable reports, and usability bar.
+
+- [Product Vision](docs/PRODUCT_VISION.md)
+- [Public Interface Model](docs/INTERFACE_MODEL.md)
+- [Contract Engine](docs/CONTRACT_ENGINE.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Type System](docs/TYPE_SYSTEM.md)
+- [Validation Engine](docs/VALIDATION_ENGINE.md)
+- [Static Typing](docs/STATIC_TYPING.md)
+- [Errors](docs/ERROR_MODEL.md)
+- [Performance and Caching](docs/PERFORMANCE.md)
+- [Testing](docs/TESTING_STRATEGY.md)
+- [Compatibility](docs/COMPATIBILITY.md)
+- [Dependencies](docs/DEPENDENCIES.md)
+- [Competition](docs/COMPETITION.md)
+- [Pydantic Integration](docs/PYDANTIC_INTEGRATION.md)
+- [Roadmap and 0.x release phases](docs/ROADMAP.md)
+- [Release and PyPI trusted publishing](docs/RELEASING.md)
+- [Design Decisions](docs/DESIGN_DECISIONS.md)
+- [Implementation Plan](docs/IMPLEMENTATION_PLAN.md)
+- [Phase 0.1 implementation contract](docs/PHASE_0_1_IMPLEMENTATION_CONTRACT.md)
+- [Open Technical Problems](docs/OPEN_TECHNICAL_PROBLEMS.md)
+- [Design probes](design_probes/README.md)
+
+The roadmap owns release scope; design decisions own durable policy; focused specifications own behavior; the open-problem register owns implementation evidence and unresolved acceptance work. Contradictions must be reconciled in the same change. A decision does not count as a tested implementation.

stipulate-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# Architecture
+
+## Overview
+
+```text
+Protocol declaration
+  -> Contract[T] facade
+  -> controlled annotation resolution and member compiler
+  -> immutable ContractIR snapshot
+  -> candidate inspection (per call)
+  -> shared capability/type relation engine
+  -> Evidence + CompatibilityResult
+  -> explicit enforcement policy
+  -> original candidate or ContractError
+```
+
+Compilation failures use `ContractDefinitionError`. Inspection does not execute candidate methods or getters. Default trusted annotation evaluation may execute annotation expressions; see VALIDATION_ENGINE.md.
+
+## Public boundary
+
+The 0.1 entry point is `Contract(ProtocolType)`. Its constructor accepts `TypeForm[T]`, preserves T through validation, and performs a runtime supported-declaration check. A normal class, union, or arbitrary type form is not automatically a valid requirement.
+
+`Contract` exposes `validate()`, `check()`, and `.contract` identity. Later `schema()`, `fingerprint()`, and `compare()` are release-gated. Experimental Interface class-side methods delegate to Contract and never become protocol instance members.
+
+## Internal modules
+
+```text
+src/stipulate/
+    __init__.py
+    _contract.py        public typed facade
+    _compile.py         requirement compilation
+    _ir.py              immutable normalized records
+    _members.py         static member classification
+    _signatures.py      binding and legal call relations
+    _assignability.py   directional type relations
+    _annotations.py     trusted/raw annotation policies
+    _compatibility.py   result aggregation and enforcement
+    _evidence.py        immutable findings
+    _errors.py          public exceptions
+    _render.py          pure plain-text result/exception presentation
+    _cache.py           weak compilation cache
+    _typing_compat.py   isolated version-specific typing behavior
+```
+
+Keep the experimental `_interface.py` bridge separate from release-critical code until accepted.
+
+## Data ownership
+
+The Contract facade strongly owns its immutable IR. The IR may strongly retain the declaration and type objects when needed to preserve identity and diagnostics. The global compilation cache must not strongly own that IR; both keys and cached IR values are weak references. See PERFORMANCE.md for lifecycle and race rules.
+
+Do not attach a globally owned adapter that closes the weak-reference lifecycle through an indirect path. Do not cache candidates or successful results globally.
+
+## Requirement versus candidate
+
+The requirement compiler has no candidate-specific state. Candidate inspection creates an ephemeral provided view with its own resolution context and evidence provenance. Expected limitations are represented as unknown facts. A current attribute value cannot substitute for a missing declared writable type.
+
+Read-only capabilities compare covariantly. Writable capabilities add contravariant write obligations. Methods compare every legal call shape, then argument/return relations. Execution-kind requirements are an explicit Stipulate policy, not inferred from textual return annotations alone.
+
+## Configuration boundaries
+
+Annotation policy and namespace identity affect compilation and cache reuse. Strictness affects enforcement only. Mutating configuration after compilation is unsupported; create a new Contract snapshot instead.
+
+Do not hold cache locks while evaluating annotations, inspecting candidate code, or comparing types. Concurrent duplicate compilation is acceptable when publication is safe and diagnostics are deterministic. Annotation evaluation must not be advertised as exactly-once under concurrency.
+
+## Presentation boundary
+
+The presenter accepts normalized evidence and sanitized display metadata. It produces text without invoking candidate code, checking compatibility again, or selecting a policy implicitly. Result str/repr and exception strings share this implementation. Later terminal or browser views may style the same facts; no view is permitted to promote UNKNOWN to compatible.
+
+## Extension rule
+
+New types and member forms add normalized representation and relation handlers with conformance tests. They must preserve unknown evidence and share rules with future evolution analysis. A public extension/plugin framework is deferred until internal semantics stabilize.

stipulate-0.1.0/docs/COMPATIBILITY.md

@@ -0,0 +1,45 @@
+# Compatibility Policy
+
+## Runtime targets
+
+Minimum package metadata is CPython 3.11 (`requires-python >=3.11`). The test targets are CPython 3.11, 3.12, 3.13, and 3.14. The implementation report records full runtime and installed-consumer verification; release approval additionally requires independent review.
+
+Advertise a minor version only after compilation, annotation resolution, signature normalization, supported type relations, evidence, lifecycle, and installed-package tests pass. Import success is insufficient. PyPy and other implementations are outside the initial support claim.
+
+Newer annotation metadata must be handled deliberately, including deferred evaluation. New interpreter features do not automatically expand the supported type-form subset. Use typing_extensions when its behavior is tested; do not invent unavailable runtime metadata.
+
+## Checkers and packaging
+
+Pyright strict is permanent for first-party code. Public fixtures also run on supported mypy configurations. Record exact versions and required feature flags; the current design probe's mypy 1.19.1 requires its TypeForm flag. No required checker plugin or consumer ignores.
+
+The TypeForm constructor and inferred return type are part of the public contract. Test installed wheels and sdists outside the source tree with py.typed and any required stubs present. Do not claim that local declaration probes prove package behavior.
+
+## Typing semantics and runtime policy
+
+The typing specification governs supported annotation relations. Strict evidence, trusted/raw annotation evaluation, static inspection limits, and the initial coroutine-kind rule are explicit Stipulate policies. Document intentional differences from ordinary checker assignment behavior.
+
+Supported constructs form a versioned subset. New support can turn UNKNOWN into COMPATIBLE or INCOMPATIBLE; treat resulting acceptance changes as observable behavior and explain them in release notes. Never market strict validation as method-body or future-value enforcement.
+
+## Versioning
+
+During 0.x, call out breaking API, policy, diagnostic, or supported-subset changes clearly. At 1.0, semantic versioning covers documented Python APIs, supported compatibility semantics, enforcement defaults, diagnostic fields/codes, and public schema versions.
+
+Correctness fixes can legitimately reject previously accepted candidates. Classify and document their impact; do not quietly claim acceptance is unchanged because a change is a bug fix.
+
+## Schema and diagnostics
+
+Public schema()/fingerprint() follow their later release gate, including explicit schema versions and identity/portability policy. Internal IR records are not a public interchange format.
+
+Diagnostic location, code, serialized fields, and semantic category become stable at 1.0. Exact human wording remains free to improve. Unknown and incompatible categories must remain distinguishable.
+
+## Mutation and evaluation
+
+Contracts are immutable requirement snapshots; refresh=True makes a new snapshot. Candidate checks are point-in-time and are repeated after candidate mutation. Trusted annotation evaluation can execute expressions; raw mode does not request evaluation and can produce unresolved evidence. Neither mode is a security boundary.
+
+## Dependencies and integrations
+
+Core results must not change merely because Pydantic or another optional integration is installed. Third-party annotation metadata is not supported implicitly. Raising Python/dependency minimums requires an explicit compatibility decision and a tested migration path.
+
+## Deprecation
+
+At 1.0, announce deprecations and normally retain them through at least one minor release, with removal in a major release. An exceptional correctness/security removal must explain why ordinary deprecation was insufficient.

stipulate-0.1.0/docs/COMPETITION.md

@@ -0,0 +1,50 @@
+# Competition and Positioning
+
+## Scope
+
+This is a positioning document, not a verified exhaustive feature ranking. Stipulate's initial implementation is in progress and its release gates remain authoritative. Planned or unsupported capabilities must not be compared as shipped advantages against other projects.
+
+Its intended focus is explicit Python structural contracts: check a dynamically supplied implementation, explain incompatible and unknown evidence, and eventually compare contract evolution with the same underlying rules.
+
+## Language foundation
+
+Protocol is the foundation. Python's typing tools already provide structural checking where the relationship is statically visible; runtime-checkable Protocol checks are intentionally shallower. Stipulate's proposed addition is deeper declaration inspection at dynamic boundaries, subject to available metadata. [Python typing documentation](https://docs.python.org/3/library/typing.html#typing.runtime_checkable)
+
+Do not claim runtime inspection proves method behavior that static checking could not prove.
+
+## Useful adjacent references
+
+| Reference | Documented focus | Stipulate design lesson |
+| --- | --- | --- |
+| Pydantic | Typed value validation and associated tooling | Simple entry points, useful diagnostics, deliberate value semantics |
+| Griffe | Package API extraction, serialization, and breaking-change analysis | Treat public schema and change reports as compatibility surfaces |
+| Typeguard | Runtime checking of annotated values and instrumented calls | Study runtime annotation limits without conflating value checks with declaration relations |
+
+Sources: [Pydantic](https://pydantic.dev/docs/validation/latest/concepts/types/), [Griffe](https://mkdocstrings.github.io/griffe/), [Typeguard](https://typeguard.readthedocs.io/en/latest/). This table does not assert that adjacent tools lack all forms of Protocol support or that Stipulate has uniquely solved those problems.
+
+Other historical interface systems, behavioral contract libraries, schema-diff tools, and API-impact projects can inform later evaluation. Specific competitive rankings require dated primary sources, concrete examples, and reproducible comparison criteria before inclusion.
+
+## Product distinction to prove
+
+The intended combination is:
+
+- Standard Protocol declarations with ordinary implementations.
+- Precise, method-based Contract API and inferred validation return types.
+- Directional call/member/type checking for an explicitly supported subset.
+- Unknown evidence preserved separately from mismatch and policy acceptance.
+- Eventual universal implementer/consumer evolution analysis using shared rules.
+- Eventual versioned schemas and portable fingerprints.
+
+The first four belong to the 0.1 plan. The last two are later release gates, not current feature claims.
+
+## Boundaries
+
+Do not expand into package-wide source extraction, general function instrumentation, call-site analytics, dependency injection, behavioral preconditions, or a nominal interface ecosystem merely to match a competitor's feature list.
+
+For tooling, a deliberate user-supplied Protocol is the contract being checked. This scope does not prevent future integrations with API extraction, but those integrations must not redefine the core.
+
+## Reassessment triggers
+
+Before publishing competitive claims or major releases, verify current primary documentation and test representative examples. Reevaluate when typing standards improve class-side APIs, checker TypeForm support changes, or adjacent projects add relevant declaration/evolution capabilities.
+
+Stipulate earns adoption through demonstrated correctness and error quality. Avoid claims of completeness, unique capability, or stronger guarantees than the evidence supports.

stipulate-0.1.0/docs/CONTRACT_ENGINE.md

@@ -0,0 +1,100 @@
+# Contract Engine
+
+## Semantic center
+
+The engine compares provided declarations against required declarations. Compatibility means each supported required operation is available with compatible call shape, binding, and types, assuming declarations describe actual behavior.
+
+One normalization and relation engine powers candidate checks and eventual evolution analysis. Relation context is explicit: metadata conformance and universal contract evolution have different obligations when gradual or unknown types are involved.
+
+## Layers
+
+1. Compile a supported Protocol into immutable `ContractIR`.
+2. Inspect a candidate into an ephemeral provided-contract view.
+3. Compare capabilities and types, producing evidence.
+4. Aggregate a policy-independent `CompatibilityResult`.
+5. Enforce strict or permissive acceptance and return the original candidate or raise `ContractError`.
+
+Later serialization and comparison consume the same IR and relation rules. They are not public 0.1 operations.
+
+## Contract IR
+
+```text
+ContractIR
+  declaration identity and diagnostic provenance
+  members
+    MethodContract: binding, legal calls, parameter types, return type, execution kind
+    AttributeContract: read type, write type, storage capability
+    PropertyContract: getter, optional setter
+  normalized TypeExpr graph
+  compilation policy and supported feature set
+```
+
+Candidate evidence and enforcement policy do not enter the requirement IR. Public `Contract[T]` is a typed facade holding one snapshot. Keep source provenance outside the semantic fields used for future serialization.
+
+Recursive references use explicit graph identities and a cycle-aware relation context. A cache of visited pairs must distinguish pending from established relations; recursion is not unconditional compatibility. Unsupported recursive forms remain explicit until dedicated support lands.
+
+## Evidence and aggregation
+
+Evidence has `PROVEN`, `INCOMPATIBLE`, or `UNKNOWN` status, a stable code and location, expected/actual metadata, provenance, and an optional actionable hint. PROVEN means an obligation about declarations was established, not that a method body was executed.
+
+Conjunctive requirements aggregate as follows:
+
+| Findings | Result status | Truthiness | Strict acceptance | Permissive acceptance |
+| --- | --- | --- | --- | --- |
+| All obligations established | COMPATIBLE | True | Yes | Yes |
+| At least one incompatible finding, with or without unknowns | INCOMPATIBLE | False | No | No |
+| No incompatibility; unknowns only from the allowlist below | UNKNOWN | False | No | Yes |
+| No incompatibility; any other unknown reason | UNKNOWN | False | No | No |
+
+`complete` means every applicable obligation was decided. It is independent of success: a fully analyzed incompatible object is complete. Blocked dependent obligations must remain explicitly unassessed; do not manufacture completeness by dropping them. An empty valid contract is compatible and complete.
+
+Disjunctive type relations use three-valued logic: one established branch suffices for an OR, all disproven branches disprove it, otherwise it is unknown. An AND is disproven by any failed obligation, established only when all succeed, otherwise unknown. Apply this inside union and other relation algorithms before aggregating independent member requirements.
+
+There is no second public assurance enum or confidence score in 0.1. `status`, `complete`, and detailed evidence suffice.
+
+## Enforcement policy
+
+`validate(candidate, strict=True)` and `result.accepted(strict=True)` share the exact same acceptance function. `check()` never applies enforcement policy.
+
+Permissive acceptance may tolerate only candidate type unknowns with codes `annotation_missing` and `gradual_type`. Known member presence, binding, signature, and execution-kind checks must still pass. Missing required members, unsupported types, unresolved expressions, unavailable signatures, dynamic members, and inspection failures cannot be waived by `strict=False`.
+
+Unknowns retain their original status and provenance after acceptance. A permissive return type is a documented trust boundary comparable to adopting untyped code, not a complete metadata proof. Invalid requirements always raise `ContractDefinitionError` independently of enforcement policy.
+
+## Exceptions
+
+`ContractError` means a valid contract rejected the candidate under the requested policy. It includes the result and the findings responsible for rejection, including unknowns rejected by strict policy.
+
+`ContractDefinitionError` means the requirement could not be compiled. `check()` does not swallow definition errors or unexpected internal defects. Expected candidate inspection limitations become unknown evidence; process-control exceptions propagate.
+
+## Evolution semantics — later release
+
+For old contract O and new contract N, under fully supported, fully static semantics:
+
+- Implementers: O is assignable to N. Every implementation meeting O also meets N.
+- Consumers: N is assignable to O. A consumer using O's operations can use N.
+
+| Change from old to new | Existing implementers | Existing consumers |
+| --- | --- | --- |
+| Add a required method | Incompatible | Compatible |
+| Remove a required method | Compatible | Incompatible |
+| Widen accepted parameter from int to object | Incompatible | Compatible |
+| Narrow returned value from object to int | Incompatible | Compatible |
+| Add an optional parameter to an existing method | May be incompatible: old implementations need not accept it | Compatible if old calls and results are preserved |
+
+These are independent perspectives, not a single “breaking” direction. Member kinds, mutability, and call shapes remain part of the analysis.
+
+Python gradual assignability involving Any is not a universal substitutability guarantee. For example, returns `int`, `Any`, and `str` permit pairwise gradual assignments through Any without making int assignable to str. Never infer transitive evolution safety through such evidence. Use the same engine with a universal-guarantee context; return UNKNOWN wherever the guarantee depends on unsupported or gradual assumptions. Independent mismatches can still establish incompatibility.
+
+`report.implementers` and `.consumers` are CompatibilityResults. `report.breaking` is True if either direction is INCOMPATIBLE, False only if both are COMPATIBLE, and None otherwise. `report.complete` requires both directions complete. CI fails on incompatible or unknown required directions by default. Report objects have no implicit truthiness; reject it to avoid ambiguous policy decisions. The CLI can explicitly select which direction matters.
+
+## Canonical schema and fingerprints — later release
+
+Versioned schema work must specify member ordering, unions, aliases, nominal type identity, generic bindings, recursive references, default presence versus default values, ignored Annotated metadata, and portability before publication.
+
+A semantic fingerprint excludes display names, source locations, and irrelevant default values. Callable compatibility depends on default presence; changed default behavior can be reported separately but is not behavioral proof. Preserve nominal identities; never merge unrelated types merely because names match. Process-local or non-portable identities must be rejected for portable snapshots or explicitly marked non-portable, not serialized using unstable repr output.
+
+Use an explicit format such as `stipulate-contract-v1:sha256:<digest>`. A fingerprint difference does not imply incompatibility. Loading snapshots must not automatically import or execute arbitrary type references.
+
+## Native implementation boundary
+
+The initial core is Python. Normalize Python inspection objects before relation analysis, but retain the runtime identity information needed for correctness. A future native core is justified only by profiling; do not constrain 0.1 around speculative Rust or force premature portable serialization.

stipulate-0.1.0/docs/DEPENDENCIES.md

@@ -0,0 +1,35 @@
+# Dependency Strategy
+
+## Core
+
+Start with standard-library dataclasses, inspect, typing, weakref, and explicit typed internal records. Stipulate owns its IR, type relations, evidence, and enforcement semantics.
+
+Use typing_extensions for TypeForm and supported cross-version features. The recorded design probes use 4.15.0; treat that as the initial tested baseline, not proof of the oldest compatible release. Freeze actual package minimums only after the release matrix passes.
+
+attrs and typing-inspection remain optional implementation evaluations, not commitments. Adopt them only if conformance experiments demonstrate a meaningful correctness or maintenance benefit. Do not add a dependency because it resembles a small standard-library abstraction.
+
+## Development
+
+Use pytest, Hypothesis, Ruff, Pyright strict, and mypy public fixtures. Pin tested checker versions and document required TypeForm settings. The specification is the semantic reference; checker/runtime-library disagreement needs an explanation rather than majority voting.
+
+Keep design probes separate from implementation tests. A local fixture dependency is not automatically a production dependency.
+
+## Later CLI
+
+Typer and Rich are preferred candidates for an optional stipulate[cli] extra once snapshot and comparison APIs are ready. CLI code consumes the shared contract engine and emits machine-readable reports independently of terminal rendering.
+
+No CLI dependency is needed for library validation or the 0.1 API.
+
+## Optional integrations
+
+Pydantic is optional and post-1.0. It must not become the assignability engine or change core outcomes based on installation state. Integration value validation needs its own no-hidden-coercion and attribute-access policy.
+
+Griffe may be evaluated if later work needs package API extraction. Typeguard and other runtime typing libraries can inform narrow differential experiments but do not define Stipulate's structural assignability semantics.
+
+## Optimization
+
+Use hashlib and json for future schema tooling once canonical semantics exist. Do not introduce Rust, PyO3, or native build infrastructure before profiling identifies a material bottleneck. Keep Python introspection on the Python side of any future native boundary.
+
+## Acceptance rule
+
+A dependency must demonstrably remove difficult non-differentiating work, improve tested compatibility, or provide a justified optional capability. Record its purpose, supported versions, typing quality, and effect on the package matrix before adoption.