Integration Examples

Purpose

The source tree now has a first-party scaffold for optional integration examples under examples/integrations/. These examples are for checkpoint-edit toolchains that want to attach InvarLock regression evidence after producing an edited subject checkpoint.

The integration surface is intentionally source-tree only. It is not part of the runtime package and should not add required dependencies to the core install.

Current Scope

Surface	Status
Shared evidence wording	Present under examples/integrations/_shared/evidence-scope.md.
Expected artifact checklist	Present under examples/integrations/_shared/expected-artifacts.md.
Shared compare wrapper	Present under examples/integrations/_shared/run_invarlock_compare.sh.
Target-specific examples	Added one target at a time after backend compatibility is validated.

Browse the integration scaffold in the repository: https://github.com/invarlock/invarlock/tree/staging/next/examples/integrations

Target Example Readiness

Target examples should declare one of these labels in their README:

Label	Meaning
runnable	Commands are expected to generate evaluation.report.json, verify.json, and evaluation.html in the documented environment.
exploratory-host	Commands run with --execution-mode host --assurance off for local dependency setup and backend investigation.
compatibility-investigation	The external artifact cannot yet be loaded or verified through the documented InvarLock path; the README records the blocker.

Preflight

Before adding or publishing a target example:

invarlock doctor
invarlock advanced plugins list --json

For optional backend targets, also check the Python module:

python -c "import importlib.util; print(importlib.util.find_spec('gptqmodel') is not None)"

Replace gptqmodel with the backend module for the target example.

Shared Workflow

For a baseline and subject that are already loadable through an InvarLock adapter:

examples/integrations/_shared/run_invarlock_compare.sh \
  --baseline sshleifer/tiny-gpt2 \
  --subject ./models/tiny-gpt2-subject \
  --report-out ./reports/integration-smoke \
  --allow-network

The generated local output should include:

Artifact	Role
evaluation.report.json	Canonical verifier input.
verify.json	Machine-readable verifier result.
evaluation.html	Human-readable report.
runtime.manifest.json	Runtime provenance for strict container-backed runs.
run_command.txt	Wrapper invocation plus evaluate, verify, and render commands.

Generated reports, models, runs, HTML, and artifacts under examples/integrations/** are ignored by git.

Public Evidence Anchors

Use the shipped public evidence as the credibility floor while target examples are being built:

invarlock verify --profile release --assurance strict \
  public_evidence/published_basis/gpt2/evaluation.report.json

invarlock verify --profile release --assurance strict \
  public_evidence/byoe_examples/lora_merge_byoe/evaluation.report.json

invarlock verify --profile release --assurance strict \
  public_evidence/real_runs/tiny_gpt2_quant_rtn/evaluation.report.json

See the Public Evidence Walkthrough for the full artifact taxonomy.