Metadata-Version: 2.4
Name: groundwork-adapter
Version: 0.1.0
Summary: Bounded fixed-pair measurement guidance with exact native replay
Requires-Python: <3.12,>=3.11
Description-Content-Type: text/markdown

# Groundwork adapter

A dependency-free scientific package for one admitted kinetics template:
`C(t) = A * (exp(-ke*t) - exp(-ka*t))`, with hours, mg/L, positive ordered
rates, `x(0)=1`, and `c(0)=0`. Qualified native runtime: **CPython 3.11**.

It compares two frozen parameter vectors on a reviewed finite grid. The
numerical tier provides finite binary64 diagnostics with an exact-input boundary.
The exact tier uses a fixed rational exponential enclosure rule, freshly checks
both candidates against every included historical hard bound, and applies the
strict margin `abs(p1-p2)-e1-e2-2*eta > 0`. Its certificate is specific to this
analytic template. It is not a general ODE checker or a global design optimizer.

Two matching candidates and an explicit positive future hard allowance are
required. A checked time can rule out fitting **both selected choices**; a datum
can exclude either or both. None of this establishes physical truth, instrument
precision, the entire compatible parameter set, or the original interval claim.

## Install and check

From the repository root, using CPython 3.11:

```sh
python3 -m pip install --no-deps ./packages/groundwork_adapter
python3 -m unittest discover -s packages/groundwork_adapter/tests -v
python3 -m groundwork_adapter capabilities
```

For source-only development, prefix commands with
`PYTHONPATH=packages/groundwork_adapter`. Build tooling is separate from the
zero-dependency runtime. No network, account, numerical solver, or provider SDK
is required for scientific work or replay.

## Run and replay the complete synthetic example

All supplied examples are synthetic. Their workflow IDs are fixture IDs, not
real approvals. The backend must validate real approval and operation scope.

```sh
python3 -m groundwork_adapter run \
  packages/groundwork_adapter/fixtures/checked_success.request.json \
  --anchors packages/groundwork_adapter/fixtures/checked_success.anchors.json \
  --output /tmp/groundwork-example.bundle.json
python3 -m groundwork_adapter replay /tmp/groundwork-example.bundle.json \
  --anchors packages/groundwork_adapter/fixtures/checked_success.anchors.json
```

The output destination must not already exist. Anchors are separate expected
identities supplied by the caller; for real review, obtain them through a trusted
channel. Replacing both a packet and its anchor does not prove authorship or
honest data collection. A source-version mismatch returns `unsupported_runtime`:
prepare the recorded package version, rather than importing anything named by
the artifact. Missing evidence returns `incomplete_export`.

`run` supports fresh candidate construction from a request file. Python callers
can also supply bounded artifact bytes to reuse an existing matching pair. A
numerical-only bundle can pass record-integrity checks but returns scientific
replay `unsupported`; it never receives an exact badge.

## Python integration

```python
from groundwork_adapter import create_suggestion, normalize_problem, normalize_design

problem = normalize_problem(reviewed_problem_projection)
design = normalize_design(frozen_design_projection, problem)
bundle_bytes = create_suggestion(
    problem.to_payload(), design.to_payload(),
    expected_problem_digest=approved_problem_digest,
    expected_design_digest=approved_design_digest,
    workflow={"plan_id": plan_id, "approval_id": approval_id,
              "operation_id": operation_id, "execution_id": execution_id},
)
```

These are **package-local scientific projections**, not competing application
transport DTOs. Owner 2 maintains the shared transport schema, authorization,
durable records and hard process supervision. The adapter supplies cooperative
cancellation and cannot authorize work. Publish a checked report and its complete
bytes atomically. Owner 3 consumes typed tiers and the fixed interpretation
selector; browser replay remains unavailable. Owner 4 qualifies deployment.

The problem identity includes row order, excluded rows, notes and provenance.
The design identity includes candidate vectors/IDs/artifact associations, grid,
allowance and origin, policies and limits. New values normalize to reduced `n/d`.
The bundle identity excludes only its named top-level `suggestion_digest` field.
Raw artifact SHA-256 hashes remain separate from DB-SC-1 semantic identities.

## Evidence and release

- [Scientific integration contract](docs/INTEGRATION.md)
- [Exact analytic argument](docs/ANALYTIC_ARGUMENT.md)
- [Automated second-reader review](docs/REVIEW.md)
- [Executed fixture ledger](fixtures/manifest.json)
- [Validation and publishing handoff](docs/VALIDATION.md)

Regenerate fixtures after any package code change:

```sh
python3 packages/groundwork_adapter/scripts/generate_fixtures.py
```

The partial fixture uses a deterministic cancellation callback; rerunning its
request through the CLI without that callback produces a new completed result.
Timing strings in the fixture ledger are observations, not latency guarantees.
The release is intentionally narrow: no provider calls, browser verification,
application routes, equipment control, or hosting are included.
