Skip to content

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

Description

@aldbr

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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions