DIRACGrid / DIRACGrid/intercede

[Feature]: Core contract (protocols, data types, typed errors)

Open
#16 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3
Forks
3
PR merge metrics
No merged PRs in 30d

Description

## User Story

As an interCEde contributor (and as DiracX, the first consumer),
I want the contract implemented as typed, async, capability-segmented Protocols with their
data types and exception hierarchy,
So that backends, fakes and consumers can all be written against one enforced contract instead of
DIRAC's abstract-by-convention base class.

## Feature Description

Implement IC-ADR-001 §1–§2, §4 (types only), §7 — the whole Tier-A surface, no real backends:

- **Protocols** (`@runtime_checkable`, async, bulk): essential `Submitter`, `Monitor` →
`JobBackend`; optional `OutputRetriever` (with `destructive: bool`), `Cancellable`, `Purgeable`,
`LoadReporter`, `SupportsLiveDiagnostics`; collaborator protocols `Transport`, `Scheduler`
(shapes only — implementations come in issues 10–12).
- **Data types**: `SubmissionSpec` (with the reserved optional `tag` field), `Submission`
(`.handles` + `.failures`), `JobHandle`/`JobID` (serialisable, routing-carrying), `JobStatus`
(incl. `UNKNOWN`), `StatusMap`, `JobOutput` (manifest: `.stdout`/`.stderr`/`.files`/`.log`),
`OpOutcome`, `JobCounts`, `Diagnostics`, `Resources`, `FileRef`, `OutputSpec`.
- **Exceptions**: rootable `InterCEdeError` hierarchy (whole-operation failures only; per-item
failures ride the outcome maps).
- **Package hygiene**: `src/intercede/` with explicit `__all__` per public module, `py.typed`,
strict mypy in CI; Tier-C modules `_`-prefixed.
- **Unit conformance suite + in-memory `FakeBackend`**: proves the contract is trivially
implementable/mockable; becomes the template for the Phase-2 integration contract suite.
- **Implement the three contract rules added to the ADR after the review pass** (all now decided
in IC-ADR-001): (a) backend/transport lifecycle — async context managers, cheap side-effect-free
construction, idempotent close (§2); (b) `JobCounts` stays counts-only — verified sufficient for
the remote family (Open Issues); (c) file ownership — `submit()` never retains caller-owned
paths after return (§4; kills DIRAC's `ExecutableToKeep`).

## Definition of Done

- [ ] Tier-A protocols + data types + exceptions importable from `intercede`, `__all__`-exported
- [ ] mypy strict green; `isinstance` narrowing works against all `@runtime_checkable` protocols
- [ ] `FakeBackend` passes the unit conformance suite (submit/status/fetch/kill, partial-failure
maps, `UNKNOWN` for unknown ids)
- [ ] Lifecycle (async context manager), counts-only `JobCounts`, and submit-time file-ownership
rules implemented as specified in the amended IC-ADR-001
- [ ] API reference docs stub builds

## Alternatives Considered

Covered by IC-ADR-001 Rejected Ideas (fat base, god-interface, sync API, ObjectLoader, reuse of
PSI/J/SAGA/blahp/Harvester/JAliEn).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.