@agoric/time 0.3.2 → 0.3.3-calypso-dev-84eb287.0

package/index.js

@@ -1,2 +1,4 @@
 export * from './src/timeMath.js';
 export * from './src/typeGuards.js';
+// eslint-disable-next-line import/export -- just types
+export * from './src/types.js';

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@agoric/time",
-  "version": "0.3.2",
+  "version": "0.3.3-calypso-dev-84eb287.0+84eb287",
   "description": "Timestamps, time math, timer service API definition",
   "type": "module",
   "main": "index.js",
+  "types": "index.js",
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^18.12 || ^20.9"
   },
   "scripts": {
     "build": "exit 0",
     "test": "ava",
     "test:xs": "exit 0",
     "lint": "run-s --continue-on-error lint:*",
-    "lint:types": "tsc -p jsconfig.json",
+    "lint:types": "tsc",
     "lint:eslint": "eslint .",
     "lint-fix": "yarn lint:eslint --fix"
   },
@@ -30,21 +31,33 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "^0.6.0",
-    "@agoric/store": "^0.9.2",
-    "@endo/nat": "^4.1.27"
+    "@agoric/assert": "0.6.1-calypso-dev-84eb287.0+84eb287",
+    "@endo/nat": "^5.0.7",
+    "@endo/patterns": "^1.4.0"
   },
   "devDependencies": {
-    "@endo/far": "^0.2.18",
-    "@endo/init": "^0.5.56",
-    "ava": "^5.2.0"
+    "@endo/far": "^1.1.2",
+    "@endo/init": "^1.1.2",
+    "ava": "^5.3.0"
+  },
+  "ava": {
+    "require": [
+      "@endo/init/debug.js"
+    ],
+    "files": [
+      "test/**/*.test.*"
+    ]
   },
   "files": [
     "*.js",
-    "NEWS.md"
+    "NEWS.md",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b66bf7c881ae462fcb617cd6e8d41b5c40ec58ef"
+  "typeCoverage": {
+    "atLeast": 87.29
+  },
+  "gitHead": "84eb287915c8255d68e845a9b6e10c790f0d54cb"
 }

package/src/timeMath.js

@@ -0,0 +1,267 @@
+import { Nat } from '@endo/nat';
+import { mustMatch } from '@endo/patterns';
+import { RelativeTimeRecordShape, TimestampRecordShape } from './typeGuards.js';
+
+/** @import {RelativeTime, RelativeTimeValue, TimerBrand, TimeMathType, Timestamp, TimestampRecord, TimestampValue} from './types.js' */
+
+const { Fail, quote: q } = assert;
+
+/**
+ * `agreedTimerBrand` is internal to this module.
+ *
+ * @param {TimerBrand | undefined} leftBrand
+ * @param {TimerBrand | undefined} rightBrand
+ * @returns {TimerBrand | undefined}
+ */
+const agreedTimerBrand = (leftBrand, rightBrand) => {
+  if (leftBrand === undefined) {
+    if (rightBrand === undefined) {
+      return undefined;
+    } else {
+      return rightBrand;
+    }
+  } else if (rightBrand === undefined) {
+    return leftBrand;
+  } else {
+    leftBrand === rightBrand ||
+      Fail`TimerBrands must match: ${q(leftBrand)} vs ${q(rightBrand)}`;
+    return leftBrand;
+  }
+};
+
+/**
+ * `sharedTimerBrand` is internal to this module, and implements the
+ * transitional brand checking and contaigion logic explained in the `TimeMath`
+ * comment. It is used to define the binary operators that should follow
+ * this logic. It does the error checking between the operands, and returns
+ * the brand, if any, that should label the resulting time value.
+ *
+ * @param {Timestamp | RelativeTime} left
+ * @param {Timestamp | RelativeTime} right
+ * @returns {TimerBrand | undefined}
+ */
+const sharedTimerBrand = (left, right) => {
+  const leftBrand = typeof left === 'bigint' ? undefined : left.timerBrand;
+  const rightBrand = typeof right === 'bigint' ? undefined : right.timerBrand;
+  return agreedTimerBrand(leftBrand, rightBrand);
+};
+
+/**
+ * `absLike` is internal to this module, and used to implement the binary
+ * operators in the case where the returned time should be a `Timestamp`
+ * rather than a `RelativeTime`.
+ *
+ * @param {Timestamp | RelativeTime} left
+ * @param {Timestamp | RelativeTime} right
+ * @param {TimestampValue} absValue
+ * @returns {Timestamp}
+ */
+const absLike = (left, right, absValue) => {
+  Nat(absValue);
+  const timerBrand = sharedTimerBrand(left, right);
+  if (timerBrand) {
+    return harden({
+      timerBrand,
+      absValue,
+    });
+  } else {
+    return absValue;
+  }
+};
+
+/**
+ * `relLike` is internal to this module, and used to implement the binary
+ * operators in the case where the returned time should be a `RelativeTime`
+ * rather than a `Timestamp`.
+ *
+ * @param {Timestamp | RelativeTime} left
+ * @param {Timestamp | RelativeTime} right
+ * @param {RelativeTimeValue} relValue
+ * @returns {RelativeTime}
+ */
+const relLike = (left, right, relValue) => {
+  Nat(relValue);
+  const timerBrand = sharedTimerBrand(left, right);
+  if (timerBrand) {
+    return harden({
+      timerBrand,
+      relValue,
+    });
+  } else {
+    return relValue;
+  }
+};
+
+// For all the following time operators, their documentation is in
+// the `TimeMathType`, since that is the documentation that shows up
+// in the IDE. Well, at least the vscode IDE.
+
+const absValue = abs => {
+  if (typeof abs === 'bigint') {
+    return Nat(abs);
+  }
+  mustMatch(abs, TimestampRecordShape, 'timestamp');
+  return Nat(abs.absValue);
+};
+
+const relValue = rel => {
+  if (typeof rel === 'bigint') {
+    return Nat(rel);
+  }
+  mustMatch(rel, RelativeTimeRecordShape, 'relative');
+  return Nat(rel.relValue);
+};
+
+const makeTimestampRecord = (abs, timerBrand) =>
+  harden({ absValue: abs, timerBrand });
+const makeRelativeTimeRecord = (rel, timerBrand) =>
+  harden({ relValue: rel, timerBrand });
+
+const coerceTimestampRecord = (ts, brand) => {
+  brand || Fail`must have a brand`;
+  if (typeof ts === 'number') {
+    ts = Nat(ts);
+  }
+  if (typeof ts === 'bigint') {
+    return makeTimestampRecord(ts, brand);
+  } else {
+    const { timerBrand } = ts;
+    mustMatch(ts, TimestampRecordShape, 'timestamp');
+    agreedTimerBrand(timerBrand, brand);
+    return ts;
+  }
+};
+
+const coerceRelativeTimeRecord = (rt, brand) => {
+  brand || Fail`must have a brand`;
+  if (typeof rt === 'number') {
+    rt = Nat(rt);
+  }
+  if (typeof rt === 'bigint') {
+    return makeRelativeTimeRecord(rt, brand);
+  } else {
+    const { timerBrand } = rt;
+    mustMatch(rt, RelativeTimeRecordShape, 'relativeTime');
+    agreedTimerBrand(timerBrand, brand);
+    return rt;
+  }
+};
+
+const addAbsRel = (abs, rel) =>
+  absLike(abs, rel, absValue(abs) + relValue(rel));
+
+const addRelRel = (rel1, rel2) =>
+  relLike(rel1, rel2, relValue(rel1) + relValue(rel2));
+
+const subtractAbsAbs = (abs1, abs2) =>
+  relLike(abs1, abs2, absValue(abs1) - absValue(abs2));
+
+const clampedSubtractAbsAbs = (abs1, abs2) => {
+  const val1 = absValue(abs1);
+  const val2 = absValue(abs2);
+  return relLike(abs1, abs2, val1 > val2 ? val1 - val2 : 0n);
+};
+
+const subtractAbsRel = (abs, rel) =>
+  absLike(abs, rel, absValue(abs) - relValue(rel));
+
+const subtractRelRel = (rel1, rel2) =>
+  relLike(rel1, rel2, relValue(rel1) - relValue(rel2));
+
+const isRelZero = rel => relValue(rel) === 0n;
+
+const multiplyRelNat = (rel, nat) => relLike(rel, nat, relValue(rel) * nat);
+
+const divideRelNat = (rel, nat) => relLike(rel, nat, relValue(rel) / nat);
+
+const divideRelRel = (rel1, rel2) => {
+  sharedTimerBrand(rel1, rel2); // just error check
+  return relValue(rel1) / relValue(rel2);
+};
+
+const modAbsRel = (abs, step) =>
+  relLike(abs, step, absValue(abs) % relValue(step));
+
+const modRelRel = (rel, step) =>
+  relLike(rel, step, relValue(rel) % relValue(step));
+
+/**
+ * `compareValues` is internal to this module, and used to implement
+ * the time comparison operators.
+ *
+ * @param {Timestamp | RelativeTime} left
+ * @param {Timestamp | RelativeTime} right
+ * @param {bigint} v1
+ * @param {bigint} v2
+ * @returns {import('@endo/marshal').RankComparison}
+ */
+const compareValues = (left, right, v1, v2) => {
+  sharedTimerBrand(left, right);
+  if (v1 < v2) {
+    return -1;
+  } else if (v1 === v2) {
+    return 0;
+  } else {
+    assert(v1 > v2);
+    return 1;
+  }
+};
+
+/**
+ * The `TimeMath` object provides helper methods to do arithmetic on labeled
+ * time values, much like `AmountMath` provides helper methods to do arithmetic
+ * on labeled asset/money values. Both check for consistency of labels: a
+ * binary operation on two labeled objects ensures that the both carry
+ * the same label. If they produce another object from the same domain, it
+ * will carry the same label. If the operands have incompatible labels,
+ * an error is thrown.
+ *
+ * Unlike amount arithmetic, time arithmetic deals in two kinds of time objects:
+ * Timestamps, which represent absolute time, and RelativeTime, which represents
+ * the duration between two absolute times. Both kinds of time object
+ * are labeled by a `TimerBrand`. For a Timestamp object, the value is
+ * a bigint in an `absValue` property. For a RelativeTime object, the value
+ * is a bigint in a `relValue` property. Thus we have a runtime safety check
+ * to ensure that we don't confused the two, even if we have managed to fool
+ * the (unsound) static type system.
+ *
+ * As a transitional measure, currently many Timestamps and RelativeTimes are
+ * still represented by unlabeled bigints. During this transitional period,
+ * we allow this, both statically and dynamically. For a normal binary
+ * operation, if both inputs are labeled, then we do the full checking as
+ * explained above and return a labeled result. If both inputs are unlabeled
+ * bigints, we *assume* that they indicate a time of the right kind
+ * (Timestamp vs RelativeTime) and timer brand. Since we don't know what
+ * brand was intended, we can only return yet another unlabeled bigint.
+ *
+ * If one operand is labeled and the other is not, we check the labeled operand,
+ * *assume* the unlabeled bigint represents the value needed for the other
+ * operand, and return a labeled time object with the brand of the labeled
+ * operand.
+ *
+ * @type {TimeMathType}
+ */
+export const TimeMath = harden({
+  absValue,
+  relValue,
+  coerceTimestampRecord,
+  coerceRelativeTimeRecord,
+  // @ts-expect-error xxx dynamic typing
+  addAbsRel,
+  // @ts-expect-error xxx dynamic typing
+  addRelRel,
+  subtractAbsAbs,
+  clampedSubtractAbsAbs,
+  subtractAbsRel,
+  subtractRelRel,
+  isRelZero,
+  multiplyRelNat,
+  divideRelNat,
+  divideRelRel,
+  modAbsRel,
+  modRelRel,
+  compareAbs: (abs1, abs2) =>
+    compareValues(abs1, abs2, absValue(abs1), absValue(abs2)),
+  compareRel: (rel1, rel2) =>
+    compareValues(rel1, rel2, relValue(rel1), relValue(rel2)),
+});

package/src/typeGuards.js

@@ -0,0 +1,23 @@
+import { M } from '@endo/patterns';
+
+export const TimerBrandShape = M.remotable('TimerBrand');
+export const TimestampValueShape = M.nat();
+export const RelativeTimeValueShape = M.nat(); // Should we allow negatives?
+
+export const TimestampRecordShape = harden({
+  timerBrand: TimerBrandShape,
+  absValue: TimestampValueShape,
+});
+
+export const RelativeTimeRecordShape = harden({
+  timerBrand: TimerBrandShape,
+  relValue: RelativeTimeValueShape,
+});
+
+export const TimestampShape = M.or(TimestampRecordShape, TimestampValueShape);
+export const RelativeTimeShape = M.or(
+  RelativeTimeRecordShape,
+  RelativeTimeValueShape,
+);
+
+export const TimerServiceShape = M.remotable('TimerService');

package/src/types.d.ts

@@ -0,0 +1,360 @@
+import type { ERef, RemotableBrand } from '@endo/eventual-send';
+
+import type { RankComparison, RemotableObject } from '@endo/marshal';
+
+/// <reference types="@agoric/notifier/src/types.js" />
+
+// These aren't in the global runtime environment. They are just types that are
+// meant to be globally accessible as a side-effect of importing this module.
+/**
+ * The TimerBrand is a unique object that represents the kind of Time
+ * used in Timestamp/RelativeTime records. Times from different sources
+ * are not comparable.
+ *
+ * Do not call `isMyTimerService(myTimerService)` on an untrusted
+ * brand, because that will leak your closely-held timer authority. If
+ * the goal is to check the suitability of a client-provided
+ * Timestamp, use coerceTimestampRecord() or add/subtract it to a
+ * known-good Timestamp, or extract its brand and === against
+ * `timerService.getTimerBrand()`.
+ *
+ * TODO Not all Timestamps are labeled with the TimerBrand (in much
+ * the same way that `Amounts` are asset/money values labeled by
+ * `Brands`), but the SwingSet vat-timer TimerService will use branded
+ * TimestampRecord/RelativeTimeRecord in all messages it emits. Also,
+ * a `TimerService` is still used everywhere a `TimerBrand` is called
+ * for.
+ *
+ * See https://github.com/Agoric/agoric-sdk/issues/5798
+ * and https://github.com/Agoric/agoric-sdk/pull/5821
+ */
+export type TimerBrand = RemotableObject & {
+  isMyTimerService: (timer: TimerService) => ERef<boolean>;
+  isMyClock: (clock: Clock) => ERef<boolean>;
+};
+
+/**
+ * @deprecated use TimestampRecord
+ *
+ * An absolute time returned by a TimerService. Note that different timer
+ * services may have different interpretations of actual TimestampValue values.
+ * Will generally be a count of some number of units starting at some starting
+ * point. But what the starting point is and what units are counted is purely up
+ * to the meaning of that particular TimerService
+ */
+export type TimestampValue = bigint;
+
+/**
+ * @deprecated use RelativeTimeRecord
+ *
+ * Difference between two TimestampValues.  Note that different timer services
+ * may have different interpretations of TimestampValues values.
+ */
+export type RelativeTimeValue = bigint;
+
+/**
+ * The canonical representation of a typed absolute time. It bundles the brand
+ * with the time, as represented by a TimerService, which might represent time
+ * since the epoch, or blockheight on a particular chain.
+ */
+export type TimestampRecord = {
+  timerBrand: TimerBrand;
+  absValue: bigint;
+};
+
+/**
+ * The canonical representation of a typed relative time. It bundles the brand
+ * with an elapsed time, as represented by a TimerService, which might represent
+ * time since the epoch, or blockheight on a particular chain.
+ */
+export type RelativeTimeRecord = {
+  timerBrand: TimerBrand;
+  relValue: bigint;
+};
+
+/**
+ * @deprecated use TimestampRecord
+ *
+ * Transitional measure until all are converted to TimestampRecord.
+ * See `TimeMath` comment for an explanation of the representation
+ * during this transition. After the transition, `Timestamp` will simplify
+ * to the current definition of `TimestampRecord`, which will itself
+ * be deleted. All Timestamps will then be labeled by TimerBrands.
+ */
+export type Timestamp = TimestampRecord | TimestampValue;
+
+/**
+ * @deprecated use RelativeTimeRecord
+ *
+ * Transitional measure until all are converted to RelativeTimeRecord
+ * See `TimeMath` comment for an explanation of the representation
+ * during this transition. After the transition, `RelativeTime` will simplify
+ * to the current definition of `RelativeTimeRecord`, which will itself
+ * be deleted. All RelativeTimes will then be labeled by TimerBrands.
+ */
+export type RelativeTime = RelativeTimeRecord | RelativeTimeValue;
+
+/**
+ * A CancelToken is an arbitrary marker object, passed in with
+ * each API call that creates a wakeup or repeater, and passed to
+ * cancel() to cancel them all. Multiple wakeups can rely on the same
+ * CancelToken so they can be cancelled collectively.
+ */
+export type CancelToken = object;
+
+/**
+ * Gives the ability to get the current time,
+ * schedule a single wake() call, create a repeater that will allow scheduling
+ * of events at regular intervals, or remove scheduled calls.
+ */
+export interface TimerServiceI {
+  /**
+   * Retrieve the latest timestamp
+   */
+  getCurrentTimestamp: () => TimestampRecord;
+  /**
+   * Return value is the time at which the call is scheduled to take place
+   */
+  setWakeup: (
+    baseTime: Timestamp,
+    waker: ERef<TimerWaker>,
+    cancelToken?: CancelToken,
+  ) => TimestampRecord;
+  /**
+   * Create and return a promise that will resolve after the absolute
+   * time has passed.
+   */
+  wakeAt: (
+    baseTime: Timestamp,
+    cancelToken?: CancelToken,
+  ) => Promise<TimestampRecord>;
+  /**
+   * Create and return a promise that will resolve after the relative time has
+   * passed.
+   */
+  delay: (
+    delay: RelativeTime,
+    cancelToken?: CancelToken,
+  ) => Promise<TimestampRecord>;
+  /**
+   * Create and return a repeater that will schedule `wake()` calls
+   * repeatedly at times that are a multiple of interval following delay.
+   * Interval is the difference between successive times at which wake will be
+   * called.  When `schedule(w)` is called, `w.wake()` will be scheduled to be
+   * called after the next multiple of interval from the base. Since times can be
+   * coarse-grained, the actual call may occur later, but this won't change when
+   * the next event will be called.
+   */
+  makeRepeater: (
+    delay: RelativeTime,
+    interval: RelativeTime,
+    cancelToken?: CancelToken,
+  ) => TimerRepeater;
+  /**
+   * Create a repeater with a handler directly.
+   */
+  repeatAfter: (
+    delay: RelativeTime,
+    interval: RelativeTime,
+    handler: TimerWaker,
+    cancelToken?: CancelToken,
+  ) => void;
+  /**
+   * Create and return a Notifier that will deliver updates repeatedly at times
+   * that are a multiple of interval following delay.
+   */
+  makeNotifier: (
+    delay: RelativeTime,
+    interval: RelativeTime,
+    cancelToken?: CancelToken,
+  ) => import('@agoric/notifier').Notifier<TimestampRecord>;
+  /**
+   * Cancel a previously-established wakeup or repeater.
+   */
+  cancel: (cancelToken: CancelToken) => void;
+  /**
+   * Retrieve the read-only Clock facet.
+   */
+  getClock: () => Clock;
+  /**
+   * Retrieve the Brand for this timer service.
+   */
+  getTimerBrand: () => TimerBrand;
+}
+// XXX copied from Remotable helper return type
+export type TimerService = TimerServiceI &
+  RemotableObject<'TimerService'> &
+  RemotableBrand<{}, TimerServiceI>;
+
+/**
+ * Read-only access to a TimeService's current time. This allows reading the
+ * current time (e.g. to see if a deadline has passed) without the ability to
+ * schedule events.
+ */
+export interface Clock {
+  /**
+   * Retrieve the latest timestamp
+   */
+  getCurrentTimestamp: () => TimestampRecord;
+  /**
+   * Retrieve the Brand for this timer service.
+   */
+  getTimerBrand: () => TimerBrand;
+}
+
+/**
+ * The interface that must be implemented by objects which are to be invoked at
+ * scheduled times. Used by `TimerService.repeatAfter()`,
+ * `TimerService.setWakeup()`, and `TimerRepeater.schedule()`.
+ */
+export interface TimerWaker {
+  /**
+   * The timestamp passed to `wake()` is the time that the call was scheduled
+   * to occur.
+   */
+  wake: (timestamp: TimestampRecord) => void;
+}
+
+/**
+ * Provides the ability to schedule wake() calls repeatedly at a regular
+ * interval, or to disable all future use of this TimerRepeater. Created by the
+ * deprecated makeRepeater(), new code should use repeatAfter(), which doesn't
+ * have a control object and doesn't require a second schedule step
+ */
+export interface TimerRepeater {
+  /**
+   * Returns the time scheduled for
+   * the first call to `E(waker).wake()`.  The waker will continue to be scheduled
+   * every interval until the repeater is disabled.
+   */
+  schedule: (waker: ERef<TimerWaker>) => TimestampRecord;
+  /**
+   * Disable this repeater, so `schedule(w)` can't
+   * be called, and wakers already scheduled with this repeater won't be
+   * rescheduled again after `E(waker).wake()` is next called on them.
+   */
+  disable: () => void;
+}
+
+/**
+ * TimeMath supports simple arithmetic on typed Time values, enforcing that
+ * values are combined in type-compatible ways. You can add 3 minutes to 3pm,
+ * or 5 minutes to a half hour, but it makes no sense to add 3pm and 5pm.
+ * Subtracting two Timestamps does produce a useful difference.
+ *
+ * The brands prevent you from accidentally combining time values from different
+ * TimerServices. Some chains track time in blocks, others follow wall clock
+ * time, some do both. Every local computer has its own unique notion of wall
+ * clock time. Even when these clocks are talking about the same thing (UTC),
+ * they can all drift in different ways. Using the correct brands lets you be
+ * precise about which particular source of time you mean, preventing confusion
+ * or attacks when the clocks diverge. Thus it is an error to e.g. use a time
+ * you got from chain A to schedule an event on chain B.
+ *
+ * The basic types are `RelativeTimeRecord` (durations) and `TimestampRecord`. The numeric
+ * values can be extracted from the typed values, but it's usually better to
+ * maintain values as their canonical typed form so these operations can be
+ * applied.
+ */
+export type TimeMathType = {
+  /**
+   * Validates that the operand represents a `Timestamp` and returns the bigint
+   * representing its absolute time value.
+   * During the transition explained in the`TimeMath` comment,
+   * `absValue` will also accept a bigint which it then just returns.
+   */
+  absValue: (abs: Timestamp) => TimestampValue;
+  /**
+   * Validates that the operand represents a `RelativeTime` and returns the
+   * bigint representing its relative time value.
+   * During the transition explained in the`TimeMath` comment,
+   * `relValue` will also accept a bigint which it then just returns.
+   */
+  relValue: (rel: RelativeTime) => RelativeTimeValue;
+
+  /**
+   * Coerces to a TimestampRecord if possible, else throws. If the value has a brand, ensure it matches.
+   * Return a Timestamp labeled with that brand.
+   */
+  coerceTimestampRecord: (
+    abs: TimestampRecord | TimestampValue | number,
+    brand: TimerBrand,
+  ) => TimestampRecord;
+  /**
+   * Coerces to a RelativeTime if possible. If a brand is provided, ensure it
+   * matches and return a RelativeTime labeled with that brand.
+   */
+  coerceRelativeTimeRecord: (
+    rel: RelativeTimeRecord | RelativeTimeValue | number,
+    brand: TimerBrand,
+  ) => RelativeTimeRecord;
+  /**
+   * An absolute time + a relative time gives a new absolute time.
+   */
+  addAbsRel: <T extends Timestamp>(
+    abs: T,
+    rel: RelativeTime,
+  ) => T extends TimestampRecord ? TimestampRecord : TimestampValue;
+  /**
+   * A relative time (i.e., a duration) + another relative time
+   * gives a new relative time.
+   */
+  addRelRel: <T extends RelativeTime>(
+    rel1: T,
+    rel2: T,
+  ) => T extends RelativeTimeRecord ? RelativeTimeRecord : RelativeTimeValue;
+  /**
+   * The difference between two absolute times is a relative time. If abs1 > abs2
+   * the difference would be negative, so this method throws instead.
+   */
+  subtractAbsAbs: (abs1: Timestamp, abs2: Timestamp) => RelativeTime;
+  /**
+   * The difference between two absolute times is a relative time. If abs1 > abs2
+   * the difference would be negative, so this method returns a zero
+   * relative time instead.
+   */
+  clampedSubtractAbsAbs: (abs1: Timestamp, abs2: Timestamp) => RelativeTime;
+  /**
+   * An absolute time - a relative time gives a new absolute time
+   */
+  subtractAbsRel: (abs: Timestamp, rel: RelativeTime) => Timestamp;
+  /**
+   * The difference between two relative times.
+   */
+  subtractRelRel: (rel1: RelativeTime, rel2: RelativeTime) => RelativeTime;
+  /**
+   * Does it represent a zero relative time, i.e., the difference
+   * of an absolute time with itself? (We choose not to define a similar
+   * isAbsZero, even though we could, because it is much less likely to be
+   * meaningful.)
+   */
+  isRelZero: (rel: RelativeTime) => boolean;
+  multiplyRelNat: (rel: RelativeTime, nat: bigint) => RelativeTime;
+  divideRelNat: (rel: RelativeTime, nat: bigint) => RelativeTime;
+  divideRelRel: (rel1: RelativeTime, rel2: RelativeTime) => bigint;
+  /**
+   * An absolute time modulo a relative time is a relative time. For example,
+   * 20:17 on July 20, 1969 modulo 1 day is just 20:17, a relative time that
+   * can be added to the beginning of any day.
+   */
+  modAbsRel: (abs: Timestamp, step: RelativeTime) => RelativeTime;
+  /**
+   * A relative time modulo a relative time is a relative time. For example,
+   * 3.5 hours modulo an hour is 30 minutes.
+   */
+  modRelRel: (rel: RelativeTime, step: RelativeTime) => RelativeTime;
+  /**
+   * Compares two absolute times. This comparison function is compatible
+   * with JavaScript's `Array.prototype.sort` and so can be used to sort an
+   * array of absolute times. The result is -1, 0, or 1 indicating whether
+   * the first argument is less than, equal, or greater than the second.
+   */
+  compareAbs: (abs1: Timestamp, abs2: Timestamp) => RankComparison;
+  /**
+   * Compares two relative times. This comparison function is compatible
+   * with JavaScript's `Array.prototype.sort` and so can be used to sort an
+   * array of relative times. The result is -1, 0, or 1 indicating whether
+   * the first argument is less than, equal, or greater than the second.
+   */
+  compareRel: (rel1: RelativeTime, rel2: RelativeTime) => RankComparison;
+};

package/src/types.js

@@ -0,0 +1,2 @@
+// Empty JS file to correspond with types.d.ts
+export {};

package/CHANGELOG.md

@@ -1,37 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-### [0.3.2](https://github.com/Agoric/agoric-sdk/compare/@agoric/time@0.3.1...@agoric/time@0.3.2) (2023-06-02)
-
-**Note:** Version bump only for package @agoric/time
-
-
-
-
-
-### [0.3.1](https://github.com/Agoric/agoric-sdk/compare/@agoric/time@0.3.0...@agoric/time@0.3.1) (2023-05-24)
-
-**Note:** Version bump only for package @agoric/time
-
-
-
-
-
-## 0.3.0 (2023-05-19)
-
-
-### Features
-
-* **auction:** add an auctioneer to manage vault liquidation ([#7000](https://github.com/Agoric/agoric-sdk/issues/7000)) ([398b70f](https://github.com/Agoric/agoric-sdk/commit/398b70f7e028f957afc1582f0ee31eb2574c94d0)), closes [#6992](https://github.com/Agoric/agoric-sdk/issues/6992) [#7047](https://github.com/Agoric/agoric-sdk/issues/7047) [#7074](https://github.com/Agoric/agoric-sdk/issues/7074)
-* create new @agoric/time package ([a61a3fb](https://github.com/Agoric/agoric-sdk/commit/a61a3fbb7a5ccfe07c715a310baa88ada8e572b2)), closes [#6003](https://github.com/Agoric/agoric-sdk/issues/6003)
-
-
-### Bug Fixes
-
-* **time:** TimerService now returns branded TimestampRecord ([9137e9c](https://github.com/Agoric/agoric-sdk/commit/9137e9cab6f459c876b1a2ad8e681be7224749ce)), closes [#6003](https://github.com/Agoric/agoric-sdk/issues/6003)
-* clean up types ([6f53f19](https://github.com/Agoric/agoric-sdk/commit/6f53f1915ce21e65fefc2fff900b7d4b947be6b1))
-* move timer files to new package ([c105bde](https://github.com/Agoric/agoric-sdk/commit/c105bdefff2527a90b3c6b9d80d0462944dd51c3))
-* TimerBrand has isMyTimerService(), not isMyTimer() ([9f4e867](https://github.com/Agoric/agoric-sdk/commit/9f4e8670694504ebbd451c8840f900a1a24b902f))
-* **time:** fix the code/test to work in its new home ([504d333](https://github.com/Agoric/agoric-sdk/commit/504d3335cf632cc50e079fb27a82db604318bd4a))