The first version of my AI harness already did useful work. It could register graphs, route model calls, apply bounded retries, validate outputs and emit structured telemetry. For one application, that was enough to prove the execution model.

Then I tried to answer a harder question: how should a second product use the same foundation?

The easiest answer would have been to copy the code or import modules from a neighboring checkout. Both approaches would make a demo work. Neither would create infrastructure that independent products could trust.

A reusable platform needs to know exactly which harness release is installed, which operations it exposes, which schemas they accept, which infrastructure versions they support and which capabilities they require. It also needs to reject a package before execution when those claims do not match reality.

That changed the problem from sharing Python files to designing a package boundary.

Source reuse creates invisible coupling

Importing another repository by path feels efficient because there is no packaging work. It also hides almost every dependency that matters.

The consumer may depend on an uncommitted file, a local directory layout or whatever branch happens to be checked out. Two environments can import different code while reporting the same application version. A change to an internal module can break consumers that were never supposed to know the module existed.

Copying the implementation creates the opposite problem. The first copy works, but fixes and policy changes immediately begin to diverge. Each product starts owning its own version of retry logic, provider adaptation, validation and telemetry.

Reusing files is not the same as reusing a platform contract.

I needed the harness to behave like a real dependency. A consumer should install a versioned artifact, import a small supported SDK and own only its domain models, workflow and adapter code. The platform should be able to validate that package without importing a sibling source checkout.

Package the contract before the behavior

I kept the public SDK deliberately small. It exports the types needed to describe a harness, bind typed entry points and register an installed definition. Internal modules can evolve as long as that public boundary remains compatible.

Each harness release carries a strict manifest. The manifest identifies the package and release, declares its compatible infrastructure range and describes every public entry point. Each entry point includes its graph and state versions plus closed input and output schemas.

A simplified definition looks like this:

Versioned harness manifest
manifest = HarnessManifest(
    harness_id="document-review",
    package_name="document-review-harness",
    version="1.0.0",
    infrastructure_requires=">=0.2.0,<0.3.0",
    required_capabilities=("model.step",),
    entry_points=(
        HarnessEntryPoint(
            entry_point_id="review",
            graph_id="document-review.review",
            graph_version="1.0.0",
            state_schema_version="1.0.0",
            input_schema=SchemaDescriptor.from_model(
                ReviewRequest,
                schema_id="document-review.request",
                version="1.0.0",
            ),
            output_schema=SchemaDescriptor.from_model(
                ReviewResult,
                schema_id="document-review.result",
                version="1.0.0",
            ),
        ),
    ),
)

The manifest contains no import path, credential or executable expression. It is safe to inspect as metadata. It explains what a release claims to provide without deciding which Python object should run.

That distinction matters. Metadata can be read and compared. Executable code must be trusted.

The manifest describes; the binding executes

The installed package also exposes a factory that returns a definition. The definition binds each declared entry point to its real request model, result model and asynchronous runner.

The registry checks the complete definition before publishing any part of it. The installed package version must match the manifest. The infrastructure version must fall inside the declared range. Required capabilities must be available. Binding names must exactly match manifest entry points. The real Pydantic schemas must match the schemas recorded in the manifest.

If one check fails, the release does not enter the registry.

This prevents a common kind of drift: documentation says an operation accepts one shape while the code accepts another. It also prevents partial registration, where one valid operation becomes visible before another invalid operation causes loading to fail.

The registry stores exact release identities. A caller selects a harness ID and version rather than asking for whichever implementation happens to be newest. That is essential for reproducibility and for continuing an execution after a newer release has been installed.

Discovery must not become automatic trust

I used standard Python distribution entry points for discovery. A harness package can advertise its factory through normal package metadata, so the host does not need a hard-coded import for every domain.

Installation still does not activate the package.

The host selects the installed factories it trusts at its composition boundary. Only those selected factories are loaded, and their distribution identity is checked before registration. An HTTP request cannot provide an arbitrary import path or ask the runtime to load any installed code.

This is an important security boundary, even though it is not a sandbox. A Python factory can execute Python. Package review and operator trust remain prerequisites.

The useful guarantee is narrower and concrete: the runtime does not confuse discoverability with permission to execute.

A definition is not a deployment

Another source of ambiguity was the word installed.

A harness release can exist as a reusable definition and also be installed on several workers. Those are different facts.

The definition says what version 1.0.0 means: its entry points, schemas, requirements and executable bindings. A deployment record says where that release was observed: the worker identity, installed package version, infrastructure version, capabilities, optional endpoint and last health observation.

Keeping these records separate avoids several false conclusions:

This separation also prepares the infrastructure for different callers. An interactive frontend, a direct API client or an external scheduler can eventually target the same registered capability without owning its deployment logic.

Test the boundary from outside the repository

Unit tests inside the infrastructure package could prove that the registry worked with local classes. They could not prove that an independent team could build a package using only the supported SDK.

For that, I created a small synthetic harness as a separate wheel. It owns its request and result schemas, publishes its own factory and imports only the public SDK. Its controlled provider exercises the real model-step executor, including a transient failure followed by a bounded retry.

I also built invalid package variants. One requires an incompatible infrastructure version. Another reports a manifest version that differs from the installed distribution. The host must reject both before they can run.

This kind of conformance test is more valuable than a mock that simply returns a fabricated success response. It verifies the same installation, discovery, schema comparison, capability checking and execution path that a real consumer uses.

It also keeps domain products out of infrastructure acceptance. The platform can prove its contract with neutral packages; each domain can later prove its own behavior against the same public boundary.

Reproducible packaging changes what evidence means

Turning the code into a package exposed problems that source-based testing had hidden.

The production image now installs the built wheel instead of importing the working directory. Tests run against that installed artifact. Fixtures, drafts and build tools stay out of the runtime package. Dependencies are pinned with hashes, and fresh offline assemblies must produce the same wheel bytes.

Strict schema testing found a subtle validation issue too. A field intended to accept an integer schema version could still accept boolean or floating equivalents through Python equality rules. An explicit exact-type check closed that gap.

These details may look small, but they change the strength of the evidence. “The tests passed in my checkout” is weaker than “this exact artifact was installed in a clean runtime, rejected incompatible consumers and was reproduced from pinned inputs.”

What this boundary does not promise

Packaging solves identity, compatibility, discovery and local typed invocation. It does not turn a local function call into governed execution.

The current boundary does not authenticate a caller, create a durable run, persist state, enforce permissions, reserve shared budgets or recover work after a process failure. A declared permission is still metadata until an admission layer verifies and enforces it. A deployment record is still an observation until a worker and health protocol exist.

Stating those limits is part of the architecture. If a local SDK call were described as a production execution API, future frontends and schedulers would build against guarantees that do not exist.

The package boundary instead creates a stable place to add those guarantees. Authentication can admit an exact harness release and entry point. Durable execution can pin the same schema and graph versions. Workers can activate selected packages. A public API can expose the capability without revealing Python imports or depending on an interactive frontend session.

Reuse begins when the boundary survives change

The most important result is not that a second wheel can be loaded. It is that the platform and the domain can now change independently within an explicit contract.

Infrastructure owns registration, compatibility checks, shared execution mechanisms and the supported SDK. A domain package owns its schemas, workflow and release decisions. Deployment configuration decides which reviewed packages become active. Callers eventually use one execution contract regardless of whether they are a frontend, an API integration or an external scheduler.

That is the difference between a working harness and reusable harness infrastructure. The graph still matters, but the reusable product is the boundary around it: versioned, inspectable, deliberately activated and tested from the consumer's side.