Feat: Core contract (Models, Protocols, exceptions) issue #16

[Alexander-Auer]

feat: core contract (protocols, data types, typed errors)

Closes #16. Implements the Tier-A contract from IC-ADR-001 (the Aug 31 revision in #4): protocols, data types and exceptions, plus an in-memory FakeBackend and a unit conformance suite. No real backends and no registry.

What's included

Public API (intercede, exported via __all__)

• Protocols (async, bulk, @runtime_checkable):
  • essential: Submitter, StatusReporter → JobBackend (with async context-manager lifecycle)
  • optional: OutputRetriever, Killable, Purgeable, Diagnosable
• Data types (frozen pydantic models, extra="forbid"): SubmissionSpec, CopyVars, FileRef, OutputSpec, OutputMember, ContainerSpec, Resources, Submission, JobHandle, JobID, JobStatus, StatusMap, JobOutput, Diagnostics, OpOutcome
• Exceptions: InterCEdeError → ConfigurationError, AuthenticationError, ResourceUnavailableError, SpecificationRejectedError

Internal (intercede._backends)

• batch/protocols.py: shapes of Transport and Scheduler (no implementations)
• fake.py: FakeBackend implementing every capability, with test hooks; conformance is checked by mypy

Package hygiene

• py.typed, strict mypy with the pydantic plugin (runs in CI through pre-commit)
• pydantic>=2 as the only runtime dependency
• mkdocs API reference stub: pixi run -e docs docs

Contract rules enforced

• File ownership: submit() reads local inputs before returning and never keeps caller paths.
• Lifecycle: construction does no I/O; closing is idempotent; a closed backend raises.
• Partial failure: whole-operation failures raise; per-job failures come back as OpOutcome(ok=False, reason=...), and unknown jobs are UNKNOWN, never dropped.
• Refuse at submit: a spec the backend can't honour (URL staging, container) raises SpecificationRejectedError.
• Path containment: file names must stay inside the working directory; output members never land outside dest.
• Secrets: CopyVars.secrets uses SecretBytes, so it never appears in repr, logs or JSON.

Deviations from the ADR (feedback welcome)

1. Per-job maps are keyed by JobHandle, not JobID. IDs are only unique within one resource; keying by ID let two clusters' job 1234 overwrite each other. JobHandle is hashable, including routing.
2. Submission.handles is a Mapping[int, JobHandle] keyed by copy index. With a list, a refused copy shifted every later handle; now handles[i] always belongs to copies[i].
3. OpOutcome[T] is generic, with a value. This lets get_output/get_diagnostics report per-job failures; kill/purge use OpOutcome[None]. A validator keeps ok/value/reason consistent.
4. Scheduler gains parse_submit(raw), parse_status(raw, ids) and workdir, which the composed backend needs. Transport gets the lifecycle methods.

If these are accepted, IC-ADR-001 should be updated to match.

Deliberately left out

• LoadReporter/JobCounts and the destructive retrieval flag: issue [Feature]: Core contract (protocols, data types, typed errors) #16 lists them, but the current ADR drops them. Adding public API later is non-breaking; removing it is not.
• Registry, credentials (IC-ADR-003), and real transports/schedulers/backends (issues 10–12).

Tests

• tests/unit/test_models.py: validation rules (hashing, secrets, name checks, OpOutcome/Submission invariants)
• tests/unit/test_protocols.py: isinstance narrowing per capability
• tests/unit/test_conformance.py: contract tests using only the public API, run through a backend fixture (honours backend_only/xfail_backend); meant to be reused against real backends
• tests/unit/test_fake_backend.py: partial failure, refusal, path containment, repeatable output

All tests run against FakeBackend only; no real scheduler or CE is involved.

Relation to other PRs

• Rebased to merge cleanly after feat: integration test scaffolding #25: unit tests live in tests/unit/ (no clash with its tests/conftest.py), and the API reference sits under docs/user/. mkdocs reports links to files outside docs/ (such as renovate.json) as info instead of failing.
• Note: feat: integration test scaffolding #25 includes the older ADR-001 commit, while this PR follows the revision in docs: ADR for migration #4. Please make sure the newer ADR is the one that lands on main.

How to check

pixi run -e py313 pytest
pixi run -e pre-commit pre-commit run --all-files
pixi run -e docs docs