Skip to content
rmichaelthomasPublic

About

A human-first, agent-friendly temporal intent primitive: meaning plus evidence before calendars, schedulers, cron, RRULE, or agents act.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Decan

Decan is a human-first, agent-friendly reference implementation for Proper Time: a small temporal-intent language for saying what time means before a scheduler, calendar, workflow, or agent turns it into action.

It is not a scheduler. It is not a calendar server. It is not a job runner. It is a deterministic temporal core: readable source goes in; canonical semantics, pinned evidence, finite resolution candidates, and replayable Occurrences come out.

Why Decan exists

Cron and RFC 5545/iCalendar recurrence rules are durable, useful standards. They are also shaped around recurrence objects. Decan starts one layer earlier: a person or agent may mean a point, window, relation, condition, boundary, exception, cadence, or context-dependent temporal rule.

Decan's job is to preserve that meaning without collapsing it into a timestamp too early.

intent fivexfive.banneker1.automation.weekly-digest
source
  kind imported_cron
  value "0 9 * * 1"
  created-at "2026-08-26T21:53:00.507Z"
  actor "5xFive Automations UI Phase 2"
time
  point 09:00
  repeat every week
context
  timezone @domain-timezone
reference domain-timezone
  kind context
  source "5xFive domain timezone America/New_York"
lifecycle
  status active
  effective-from 2026-08-31

What is implemented

  • Human-readable authoring and strict canonical source for temporal intent.
  • JSON interchange with stable canonical hashes.
  • Semantic validation with stable error codes.
  • Exact snapshot-only temporal resolution with a public resolver support matrix.
  • Explicit context snapshot adapters for timezone, calendar, locale, observer/reference facts, location, participant, availability, astronomical, and custom context.
  • Civil-time gap/fold handling from pinned timezone rules.
  • Series resolution: resolveSeries expands a recurring compound (a repeat stride, week- or month-scoped weekday selections, one clock point, per-date EXDATE suppression, COUNT/UNTIL) into a finite occurrence list over a window, with gaps and folds reported rather than resolved by policy.
  • Loss-aware cron/RRULE adapters over an exact fail-closed subset, each with a TemporalLossReport that records exact preservation or an explicit unsupported conversion.
  • SQLite-backed append-only Occurrences with materialization/replay checks.
  • Executable consumer evidence for 5xFive, Seshat, and the Cloudflare backward-channel package.
  • A CLI for direct parsing, validation, support classification, resolution, adapter interop, and materialization.
  • An MCP stdio server exposing Decan tools, resources, and prompts to agent hosts.
  • Public Proper Time dissemination materials: corpus page, launch argument, and standalone landing page.

Human-first and agent-friendly

Decan intentionally has multiple surfaces:

  • Human surface: readable temporal source centered on time, not opaque recurrence strings.
  • Canonical surface: deterministic indentation-structured documents for review and diffing.
  • Programmatic surface: typed TypeScript objects and JSON interchange.
  • Runtime surface: validation, exact support classification, deterministic resolution, materialization, and capability reporting.

That was the original design target: humans should not have to think like cron, and agents should not have to guess what a human meant.

Interop with cron, RRULE, and iCalendar

Decan does not claim to replace RFC 5545/iCalendar. It treats cron and RRULE as interchange targets when fidelity is possible.

The exact adapter subset supports:

  • RRULE with explicit local DTSTART: FREQ=DAILY|WEEKLY|MONTHLY|YEARLY with any INTERVAL, and COUNT or UNTIL;
  • EXDATE values, carried as @exdate: markers and applied per date by resolveSeries;
  • MONTHLY positional and weekday-set BYDAY (2TU, -1FR, TU,TH);
  • WEEKLY weekday sets (BYDAY=MO,WE, or a single weekday that differs from DTSTART), and DAILY;INTERVAL=1 with BYDAY as its exact weekly equivalent;
  • WKST=MO at any interval, and any other WKST at INTERVAL=1;
  • export of the same shapes back to DTSTART + RRULE (+ EXDATE);
  • cron shaped like 0 9 * * 1 (weekly), 0 9 15 * * (monthly by day), and 0 9 25 12 * (yearly).

BYSETPOS, BYMONTHDAY, BYMONTH, BYYEARDAY, BYWEEKNO, RDATE, RECURRENCE-ID, and VTIMEZONE remain unsupported, as do monthly rules starting on the 29th–31st and yearly rules starting on Feb 29 (RRULE skips the missing days; Decan cannot). docs/conformance.md has the full list and the exact series semantics.

Unsupported or lossy shapes fail closed with capability errors. Every adapter result includes a TemporalLossReport: exact conversions name the preserved semantics, while rejected conversions name the consequence and remediation. Decan never emits an apparently valid cron/RRULE expression while pretending discarded semantics were preserved.

Boundaries

Decan does not authorize, execute, retry, verify, or fulfill work. It has no ambient locale, timezone, clock, geolocation, network, or dynamic-observer fallback.

Missing context remains a typed need; supplied context must be explicit evidence. Live observers are out of core. Future observer systems should emit pinned snapshots for Decan to consume.

Repository map

CLI

After building, Decan exposes a command surface:

npm run build
node dist/cli/index.js canonicalize fixtures/consumer-evidence/5xfive-banneker1-cron-trigger/authoring.ti
node dist/cli/index.js import-cron "0 9 * * 1" --effective-from 2026-08-27

When installed as a package, the binaries are:

decan canonicalize intent.ti
decan validate intent.ti
decan support intent.ti
decan resolve intent.ti --reference-time 2026-08-27T12:00:00Z --horizon-count 3 --context context.json
decan import-cron "0 9 * * 1" --effective-from 2026-08-27
decan import-rrule --dtstart 20260831T090000 --rrule FREQ=WEEKLY\;INTERVAL=1\;BYDAY=MO
decan materialize --intent-id example.weekly --intent-version 1 --resolution resolution.json --candidate-id sha256:candidate --recorded-at 2026-08-27T21:53:00Z

MCP

Decan also ships a stdio MCP server:

decan-mcp

It exposes these tools:

  • decan_canonicalize
  • decan_validate
  • decan_classify_support
  • decan_resolve
  • decan_import_cron
  • decan_import_rrule
  • decan_export_rrule
  • decan_materialize

It also exposes read-only resources for the spec, conformance guide, Proper Time corpus, and launch argument, plus prompts for explaining temporal intent and converting schedules into Decan with honest gaps.

Development

npm install
npm run typecheck
npm test -- --cache=false
npm run build

Decan currently requires Node.js >=22.13.0 because the durable Occurrences adapter uses node:sqlite.

Edge runtimes

Import from @rmichaelthomas/decan/temporal on Cloudflare Workers, Deno, or the browser. It exports the same surface as the package root, including resolveSeries and the RRULE adapters, minus SQLiteOccurrenceStore, the only module that imports a Node builtin. Edge consumers supply their own OccurrenceStore.

import { importRRule, resolveSeries } from "@rmichaelthomas/decan/temporal";

Public site

The static Decan showcase lives in site/. After this repository's Pages source is set to GitHub Actions, the deployment workflow publishes only that directory after pushes to main.

Status

The initial primitive is built out through the v1.2 world-readiness checkpoint, v1.3 public-packaging pass, v1.4 public-interface sprint, and v1.5 release, loss-evidence, scientific-time, and service-exploration sprint:

  • temporal-core.resolve is exact over Decan's declared support matrix.
  • cron/RRULE interop has an exact fail-closed subset, and resolveSeries expands every imported RRULE shape into occurrences.
  • live dynamic observers are closed as unsupported in core.
  • public packaging now states the Decan / Proper Time positioning, support claims, examples, and non-goals.
  • CLI and MCP surfaces now make Decan directly usable by humans, scripts, CI, and agent hosts.
  • adapter outputs now carry TemporalLossReport evidence for exact and unsupported cron/RRULE conversions.
  • the scientific-time spike demonstrates satellite and mission-planning applicability with pinned astronomical snapshots, without claiming scientific-scale transformation or ephemeris authority.
  • service exploration defines managed snapshot, MCP, replay, and connector possibilities that remain outside the open temporal core.

Decan is licensed under Apache-2.0. The core, reference implementation, and public specification materials are reusable infrastructure; managed snapshot, MCP, audit, and connector services remain separate products.

About

A human-first, agent-friendly temporal intent primitive: meaning plus evidence before calendars, schedulers, cron, RRULE, or agents act.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages