Duration application check

duration-application-check · version 1.0.0 · Dates & times (UTC, ISO 8601) · free, no key needed

Check a claimed timestamp from adding or subtracting an ISO 8601 duration under explicit offset and month-end rules.

Use when you need to: check timestamp plus iso duration result · verify date after adding P1M to january 31 · validate claimed end time of a duration.

Decide before calling

Read the versioned contract and the supported scope below. Reuse duration-application-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 duration-application-check@1.0.0 for check timestamp plus iso duration result. 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 timestamp plus iso duration result
• verify date after adding P1M to january 31
• validate claimed end time of a duration
• did the agent subtract the duration correctly
• check month end clamping when adding months
• audit rfc 3339 timestamp plus period

Not supported

• IANA time zones or daylight-saving transitions (fixed offsets only)
• leap seconds (second 60) and sub-nanosecond fractions
• fractional years, months, weeks or days
• business-day or holiday calendars

Behavior

• Reference: ISO 8601-1:2019 durations with designators (years, months, weeks and days are nominal calendar units; hours, minutes and seconds are exact) and RFC 3339 section 5.6 date-time; reference_version is returned with every result.
• start and claim timestamps: RFC 3339 date-time YYYY-MM-DDTHH:MM:SS.1-9 digits, T and Z may be lower case, years 0000-9999 proleptic Gregorian; second 60 and more than 9 fractional digits are unsupported_input.
• duration: ISO 8601-1:2019 designator format; calendar components must be whole and the time part a whole number of nanoseconds (else unsupported_input).
• offset_policy (required): keep_start_offset does the calendar steps on the local date in the start offset and writes the result in that offset (-00:00 stays -00:00); utc does them on the UTC date and writes Z.
• Order of application: total months 12Y + M first (rollover policy on the local date), then 7W + D calendar days on the local date (time of day kept), giving calendar_result; then the exact time 10^9 (3600H + 60M + S) nanoseconds on the instant, giving result. direction subtract negates every component and keeps the same order.
• rollover (required): clamp moves a nonexistent day to the last day of the month (Jan 31 + P1M = Feb 28/29); overflow carries the excess days into the next month (Jan 31 + P1M = Mar 2/3); reject makes the claim invalid with reason day_overflow_rejected and invalid_local_date.
• Comparison order: claim.calendar_result (when given) then claim.result; each first by instant (difference_nanoseconds = claimed - actual), then by offset. A local date outside 0000-9999 gives reason result_out_of_range. actual is the canonical RFC 3339 text (uppercase T and Z, minimal fraction, Z for a zero offset).

Input

• start (string, required): min length 20; max length 64
• duration (string, required): max length 100
• direction (one of "add", "subtract", required)
• offset_policy (one of "keep_start_offset", "utc", required)
• rollover (one of "clamp", "overflow", "reject", required)
• claim (object, required)

Output

• valid (boolean, required)
• reason (one of null, "day_overflow_rejected", "result_out_of_range", "calendar_instant_mismatch", "calendar_offset_mismatch", "instant_mismatch", "offset_mismatch", required)
• first_discrepancy (object or null, required)
• reference_version (string, required)

Limits

• max duration chars: 100
• max timestamp chars: 64

Example

Request input:

{
  "start": "2024-01-31T10:00:00Z",
  "duration": "P1M",
  "direction": "add",
  "offset_policy": "keep_start_offset",
  "rollover": "clamp",
  "claim": {
    "result": "2024-02-29T10:00:00Z"
  }
}

Response:

{
  "result": {
    "valid": true,
    "reason": null,
    "first_discrepancy": null,
    "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), then call execute with:

{
  "id": "duration-application-check",
  "version": "1.0.0",
  "input": {
    "start": "2024-01-31T10:00:00Z",
    "duration": "P1M",
    "direction": "add",
    "offset_policy": "keep_start_offset",
    "rollover": "clamp",
    "claim": {
      "result": "2024-02-29T10:00:00Z"
    }
  }
}

HTTP (no key)

curl -X POST https://computefirst.net/v1/tools/duration-application-check/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"start":"2024-01-31T10:00:00Z","duration":"P1M","direction":"add","offset_policy":"keep_start_offset","rollover":"clamp","claim":{"result":"2024-02-29T10:00:00Z"}}'

The machine-readable contract is at /v1/tools/duration-application-check/versions/1.0.0.

CLI

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

Get the client at /clients/cli/.

Related tools

• ISO duration structure check: Check a claimed reading of an ISO 8601 duration: well-formedness, components and month/day/time totals.
• ISO date month end: Return the last valid calendar day of the year-month of a YYYY-MM-DD date.
• ISO date quarter bounds: Return the calendar quarter number and the first/last dates of the quarter containing a date.
• Appointment request check: Check an appointment request against pinned time-zone facts and caller-supplied booking rules.
• ISO date add: Add a signed whole-day delta to a strict YYYY-MM-DD calendar date.
• ISO date add months: Add a signed month count to a YYYY-MM-DD date, clamping the day to the target month.