# Interval duration check

`interval-duration-check` · version 1.0.0 · Numbers & math · free, no key needed

Check a claimed duration between two RFC 3339 instants as exact elapsed time or as a calendar duration.

**Use when you need to: check elapsed time between two timestamps · verify claimed duration between start and end · validate years months days between two dates.**

## Decide before calling

Read the [versioned contract](/v1/tools/interval-duration-check/versions/1.0.0) and the supported scope below. Reuse `interval-duration-check@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `interval-duration-check@1.0.0` for check elapsed time between two timestamps. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- check elapsed time between two timestamps
- verify claimed duration between start and end
- validate years months days between two dates
- is PT36H the right elapsed time
- check calendar difference of two instants
- audit nanoseconds between rfc 3339 times

## Not supported

- IANA time zones or daylight-saving rules (fixed offsets only)
- leap-second counting (UTC seconds are 86400 per day)
- negative intervals (end before start)
- business days or working hours between dates

## Behavior

- Reference: ISO 8601-1:2019 durations and time intervals (start no later than end) and RFC 3339 section 5.6 date-time; reference_version is returned with every result.
- start and end: RFC 3339 date-time with offset (same rules as duration-application-check); end before start is invalid_input.
- mode elapsed: exact time only. claim.elapsed_nanoseconds is the integer end - start in nanoseconds; claim.duration must use only H, M, S (any nominal Y, M, W or D component gives reason nominal_component) and its exact total must equal the elapsed time. offset_policy and rollover must be omitted.
- mode calendar_balanced: claim.duration must equal the balanced decomposition: the largest whole month count m with start + m months <= end (rollover on the local date), years = floor(m / 12), months = m mod 12, weeks 0, then whole days, then hours < 24, minutes < 60, seconds < 60 with up to 9 fractional digits.
- mode calendar_consistent: applying claim.duration to start (months, then days, then exact time, as in duration-application-check) must give exactly the end instant; reason end_mismatch otherwise.
- Calendar modes require offset_policy (keep_start_offset: local dates in the start offset; utc) and rollover (clamp or overflow); the end is viewed in the same frame.
- Comparison order: elapsed_nanoseconds then duration (elapsed); years, months, weeks, days, hours, minutes, seconds (balanced). actual values are canonical: integer nanoseconds, decimal components, PT..H..M..S text, or RFC 3339 text.

## Input

- `start` (string, required): min length 20; max length 64
- `end` (string, required): min length 20; max length 64
- `mode` (one of "elapsed", "calendar_balanced", "calendar_consistent", required)
- `offset_policy` (one of "keep_start_offset", "utc", optional)
- `rollover` (one of "clamp", "overflow", optional)
- `claim` (object, required)

## Output

- `valid` (boolean, required)
- `reason` (one of null, "elapsed_mismatch", "nominal_component", "duration_mismatch", "component_mismatch", "end_mismatch", required)
- `first_discrepancy` (object or null, required)
- `mode` (one of "elapsed", "calendar_balanced", "calendar_consistent", required)
- `reference_version` (string, required)

## Limits

- max duration chars: 100
- max timestamp chars: 64
- max claim chars: 100

## Example

Request input:

```json
{
  "start": "2024-03-09T12:00:00Z",
  "end": "2024-03-11T00:00:00Z",
  "mode": "elapsed",
  "claim": {
    "duration": "PT36H",
    "elapsed_nanoseconds": "129600000000000"
  }
}
```

Response:

```json
{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "mode": "elapsed",
    "reference_version": "ISO 8601-1:2019 durations (designator format) + RFC 3339 (2002) timestamps; r66-duration-claim-verifiers@1.0.0"
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "interval-duration-check",
  "version": "1.0.0",
  "input": {
    "start": "2024-03-09T12:00:00Z",
    "end": "2024-03-11T00:00:00Z",
    "mode": "elapsed",
    "claim": {
      "duration": "PT36H",
      "elapsed_nanoseconds": "129600000000000"
    }
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/interval-duration-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"start":"2024-03-09T12:00:00Z","end":"2024-03-11T00:00:00Z","mode":"elapsed","claim":{"duration":"PT36H","elapsed_nanoseconds":"129600000000000"}}'
```

The machine-readable contract is at [/v1/tools/interval-duration-check/versions/1.0.0](/v1/tools/interval-duration-check/versions/1.0.0).

### CLI

```sh
node cli.mjs run interval-duration-check 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [Linear residual check](/tools/linear-residual-check): Check a claimed residual r = b - A x (per component and/or its max norm) exactly for an approximate solution x.
- [Lp primal feasibility check](/tools/lp-primal-feasibility-check): Check that a claimed LP point satisfies x >= 0 and Ax <= b exactly; report the first violated bound or row.
- [Multiset difference check](/tools/multiset-difference-check): Check claimed left-only and right-only scalar bag differences in deterministic source order.
- [Network cut capacity check](/tools/network-cut-capacity-check): Check a claimed s-t cut: source-side membership, the edges crossing it and its capacity, with exact integers.
- [Network flow feasibility check](/tools/network-flow-feasibility-check): Check a claimed s-t flow for capacity bounds and conservation with exact integers; returns the first bad edge or node.
- [Polynomial factorization check](/tools/polynomial-factorization-check): Check a claimed factorization c * prod f_i^e_i of a rational polynomial: monic distinct factors, degrees, coefficients.