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

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions