Metadata-Version: 2.4
Name: future-claim-certifier
Version: 1.1.0
Summary: Replayable Python protocol engine for validating time-bound future claims from canonical artifacts.
Project-URL: Documentation, https://github.com/kadubon/future-claim-certifier#readme
Project-URL: Homepage, https://doi.org/10.5281/zenodo.21199529
Project-URL: Issues, https://github.com/kadubon/future-claim-certifier/issues
Project-URL: Paper, https://doi.org/10.5281/zenodo.21199529
Project-URL: Source, https://github.com/kadubon/future-claim-certifier
Author: DFCC contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-safety,artifact-bundles,auditability,authority-validation,canonical-artifacts,canonical-json,future-claims,json-schema,proof-checking,protocol-engine,runtime-verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: referencing>=0.35.1
Requires-Dist: rfc8785>=0.1.4
Description-Content-Type: text/markdown

# Future Claim Certifier

Future Claim Certifier is a Python implementation of Dynamic Future-Claim
Certification (DFCC). It checks whether a time-bound claim about a future state
can be used as authority, and it explains why the answer is allow, deny,
unknown, expired, blocked, or conflicting.

The project is designed for software agents, auditors, and protocol engineers
who need decisions that can be replayed later from the same files. Every
important input is a canonical artifact with a digest, schema, reason path, and
typed outcome.

Paper: Takahashi, K. (2026). *Dynamic Future-Claim Certification: A Replayable
Authority Validation Protocol with Canonical Artifacts*. Zenodo.
https://doi.org/10.5281/zenodo.21199529

## What It Does

DFCC separates three questions that are often mixed together:

- What was certified at issue time?
- Is the certificate still active at use time?
- Is the requested use allowed for this context?

The package implements the protocol layer:

- canonical JSON and digest identity;
- artifact bundles and reference resolution;
- schema/profile validation;
- accepted evidence and audit-only raw evidence;
- bounded certificate issuance;
- lifecycle/status replay;
- represented and operational authority checks;
- golden conformance cases.

It is not a general solver. The bundled backend is an exact finite-state
reference backend for small examples and tests. Larger solvers, simulators, or
proof engines can be connected behind the checker interfaces.

## Install

For users:

```bash
python -m pip install future-claim-certifier
dfcc conformance run --suite primary
```

For local development:

```bash
uv sync --locked --all-groups
uv run dfcc conformance run --suite primary
```

Python 3.11 or newer is supported. The import package is `dfcc`; the command
line tool is `dfcc`.

## Five-Minute CLI Flow

Strict authority starts from an artifact bundle. The bundle contains the claim,
time basis, accepted clauses or explicit trust assumptions, proof references,
and a manifest digest. Use this path for decisions that another process or
agent will rely on later:

```bash
uv run dfcc validate-bundle artifact-bundle.json --full-replay
uv run dfcc certify-bundle artifact-bundle.json --out issue.json
uv run dfcc replay-status --bundle artifact-bundle.json
```

The direct safe-temperature example is useful for learning and migration. It is
not the strict authority path unless synthetic trust is explicitly allowed:

```bash
uv run dfcc certify examples/safe_temperature/spec.json --out issue.json
uv run dfcc check \
  issue.json \
  examples/safe_temperature/proposed_use.json \
  examples/safe_temperature/status_context.json \
  --allow-synthetic-trust \
  --out status-view.json
```

Without `--allow-synthetic-trust`, direct checks return a blocking `unknown`
when the evidence is not bound to artifacts. This default prevents embedded
source, raw evidence, or unstated trust from becoming authority.

Check whether a represented use is allowed from a strict bundle:

```bash
uv run dfcc validate-bundle artifact-bundle.json --full-replay --out report.json
```

Run packaged conformance suites:

```bash
uv run dfcc conformance run --suite primary
uv run dfcc conformance run --suite legacy
uv run dfcc conformance run --suite strict
```

Replay lifecycle/status data directly from a bundle:

```bash
uv run dfcc replay-status --bundle artifact-bundle.json
```

List and export schemas:

```bash
uv run dfcc schema list
uv run dfcc schema export issue-certificate.schema.json --out issue-schema.json
```

## Python Example

```python
from dfcc.certificate import certify_claim_from_artifact_bundle
from dfcc.validation import validate_artifact_bundle

report = validate_artifact_bundle(artifact_bundle, full_replay=True)
view = report.authority_view

if view is not None and view.authority_outcome.code == "assert" and not view.blocking_set:
    use_claim_as_represented_authority()
else:
    inspect_blocking_records(report.final_result)
```

For strict artifact-bundle issuance, use:

```python
certificate = certify_claim_from_artifact_bundle(artifact_bundle)
```

The strict path uses accepted clauses or explicit trust assumptions. Raw
evidence is audit data only and cannot silently change the certified semantics.
Strict replay also requires the bundle manifest digest. A missing digest becomes
`missing_ref`; a stale digest becomes `digest_mismatch`.

The direct convenience API is retained for migration and local examples:

```python
from dfcc import check_authority
from dfcc.certificate import certify_claim

certificate = certify_claim(claim, bundle, anchor, time_basis)
view = check_authority(
    certificate,
    proposed_use,
    status_context,
    allow_synthetic_trust=True,
)
```

Without `allow_synthetic_trust=True`, direct inputs are normalized as synthetic
trust and return a blocking `unknown` result instead of represented `assert` or
`deny`, or operational `accept` or `reject`.

## Reading Outcomes

DFCC is conservative. Missing or conflicting evidence is never upgraded into an
allowing result.

Common results:

- `assert`: the represented claim is currently usable as true for the requested
  represented use.
- `deny`: the represented claim is currently usable as false for the requested
  represented use.
- `accept`: the operational target is allowed after observation, completion,
  fiber, adjudication, adequacy, and policy checks.
- `reject`: the operational target is rejected by those checks.
- `unknown`: more accepted evidence or proof material is needed.
- `expired`: the status time is outside the certificate validity window.
- `out_of_frame`: the requested use is outside the certified frame.
- `conflict`: artifacts, lifecycle traces, or proof records disagree.
- `policy_block`: the protocol result exists, but policy does not allow use.
- `checker_unknown`: proof, checker, admission, or synthetic-trust evidence is
  missing or not accepted.
- `missing_ref`, `digest_mismatch`, `schema_invalid`, `artifact_conflict`:
  strict replay stopped before authority because artifact evidence did not
  resolve cleanly.

For non-allowing outcomes, inspect `blocking_records`, `failure_records`, and
typed `reason_ref_records`. They identify the artifact digest and JSON Pointer
path that caused the decision.

## Documentation

- [Docs index](docs/index.md): start here for learning paths.
- [Architecture](docs/architecture.md): main concepts and trust boundaries.
- [Agent usage](docs/agent-usage.md): safe use by autonomous agents.
- [Protocol mapping](docs/protocol-mapping.md): paper definitions mapped to API,
  schemas, failure codes, and conformance cases.
- [Release checklist](docs/release-checklist.md): pre-publish audit steps.
- [Security policy](SECURITY.md): security model and reporting.
- [Contributing](CONTRIBUTING.md): local development commands.

## Release And Quality Gates

The repository CI runs:

- ruff format and lint;
- mypy strict type checking;
- pytest with coverage gate at 90% or higher;
- bandit;
- pip-audit;
- primary and legacy conformance suites;
- strict conformance cases that prove raw evidence, embedded source, missing
  manifest digest, and unbound proof refs cannot authorize a claim;
- package build and distribution metadata checks.

PyPI publishing uses GitHub Actions Trusted Publishing. No long-lived PyPI API
token is required.

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
