@wirecat/cli-base 0.47.5 → 0.49.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.49.0 — 21.10.2026
+
+### Added
+
+- **`parseLucene` can read a phrase's distance.** With `{ proximity: true }`, `"a b"~3` parses as a phrase predicate
+  with `slop: 3`, and `queryNodeSchema` accepts `slop`. Meeting search needs it for words spread over neighbouring
+  transcript lines, and a caller that turns it on says what the number counts. Without the option `~` is still
+  `query.unsupported-operator`, so messages and lists see no change. A distance that is not a whole number is
+  `query.invalid-syntax`; `word~2` (fuzzy) stays unsupported either way.
+
+## 0.48.0 — 21.10.2026
+
+### Changed — may break callers
+
+- **The handbook has a Time page, and the shared CI runs tests in `Asia/Vladivostok`.** Every time is stored and
+  exchanged in UTC; a zone is applied only where a time with no zone comes in and where a person reads one
+  ([`docs/standards/time.md`](docs/standards/time.md), `WC-TIME-1`…`6`). `WC-OUT-13` now asks for ISO 8601 ending
+  in `Z`, not any zone. `node-ci.yml` sets `TZ=Asia/Vladivostok` for `test:coverage`, so a test that passed only
+  because CI ran in UTC fails. What to watch for: a repository that moves its `node-ci.yml` pin to this release may
+  see tests fail that read or print local dates; those are the bugs the Time page names.
+
+### Added
+
+- **`wallTime(value, zone, span)` in `@wirecat/cli-base/query`** reads a time with no zone (`2026-10-21T16:03`,
+  optional seconds) as the moment it names in an IANA zone, whatever the process zone. A local time that daylight
+  saving skips or repeats is refused with `validation_error`, never guessed. It is the input edge `WC-TIME-3` asks
+  for; cli-core's `--since-time` and `--at-time` parsers are to move onto it.
+- **`zonedMoment(value, zone, span, { end? })` in `@wirecat/cli-base/query`** reads a typed date or time the way
+  `WC-TIME-3` and `WC-TIME-5` ask: a zone the value names wins, a time without one is read in `zone`, a date alone is
+  local midnight, or with `end` the last millisecond of that local day.
+- **`meta.timezone` and `meta.window`** are allowed in every envelope: the zone a time without one was read or shown
+  in, and the UTC `{ since?, until? }` a date filter used.
+
+### Fixed
+
+- **`fakeClock(startMs).now()` starts at `startMs`.** It reported `2 × startMs` plus the time slept, so a test that
+  gave a start time saw a different wall time than it set. What to watch for: a test that worked around the doubled
+  value now sees the value it passed.
+
 ## 0.47.5 — 21.10.2026
 
 ### Fixed

package/dist/query/dates.d.ts

@@ -1,6 +1,15 @@
 import { type Span } from "./types.js";
 export declare const timezoneOf: (given?: string) => string;
 export declare const dayBoundary: (value: string, zone: string, next: boolean, span: Span) => number;
+/** A time with no zone, read in `zone`. A local time that daylight saving skips or repeats is refused. */
+export declare const wallTime: (value: string, zone: string, span: Span) => number;
+/**
+ * A typed date or time as epoch ms. A zone the value names wins; else it is read in `zone`. A date alone is the
+ * start of that local day, or with `end` its last millisecond, so an inclusive `<=` keeps the whole day.
+ */
+export declare const zonedMoment: (value: string, zone: string, span: Span, { end }?: {
+    end?: boolean | undefined;
+}) => number;
 export interface DateRange {
     lower?: number;
     upper?: number;

package/dist/query/dates.js

@@ -50,6 +50,60 @@ export const dayBoundary = (value, zone, next, span) => {
         queryError("query.invalid-date", span, "this calendar day does not exist in the selected timezone");
     return lo;
 };
+const WALL = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/u;
+/** A time with no zone, read in `zone`. A local time that daylight saving skips or repeats is refused. */
+export const wallTime = (value, zone, span) => {
+    const [, year, month, day, hour, minute, second = "0", fraction = "0"] = WALL.exec(value) ?? [];
+    if (year === undefined)
+        queryError("query.invalid-date", span, "use YYYY-MM-DDTHH:mm, with optional seconds");
+    const wanted = Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second), Number(fraction.padEnd(3, "0")));
+    const check = new Date(wanted);
+    if (check.getUTCDate() !== Number(day) ||
+        check.getUTCHours() !== Number(hour) ||
+        check.getUTCMinutes() !== Number(minute) ||
+        check.getUTCSeconds() !== Number(second))
+        queryError("query.invalid-date", span);
+    const formatter = new Intl.DateTimeFormat("en-CA", {
+        timeZone: zone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+    });
+    const shown = (instant) => {
+        const parts = Object.fromEntries(formatter.formatToParts(instant).map((part) => [part.type, Number(part.value)]));
+        return (Date.UTC(parts.year ?? 0, (parts.month ?? 1) - 1, parts.day, parts.hour, parts.minute, parts.second) +
+            (((instant % 1000) + 1000) % 1000));
+    };
+    const found = new Set();
+    for (const probe of [wanted - 86_400_000, wanted, wanted + 86_400_000]) {
+        const candidate = wanted - (shown(probe) - probe);
+        if (shown(candidate) === wanted)
+            found.add(candidate);
+    }
+    if (found.size !== 1)
+        queryError("query.invalid-date", span, "this local time is skipped or repeated by daylight saving; add an offset");
+    return [...found][0];
+};
+const ZONED = /(?:Z|[+-]\d{2}:?\d{2})$/iu;
+/**
+ * A typed date or time as epoch ms. A zone the value names wins; else it is read in `zone`. A date alone is the
+ * start of that local day, or with `end` its last millisecond, so an inclusive `<=` keeps the whole day.
+ */
+export const zonedMoment = (value, zone, span, { end = false } = {}) => {
+    if (/^\d{4}-\d{2}-\d{2}$/u.test(value))
+        return dayBoundary(value, zone, end, span) - (end ? 1 : 0);
+    if (!ZONED.test(value))
+        return wallTime(value, zone, span);
+    const time = Date.parse(value);
+    if (!/^\d{4}-\d{2}-\d{2}T/u.test(value) || !Number.isFinite(time))
+        queryError("query.invalid-date", span);
+    calendar(value.slice(0, 10), span);
+    return time;
+};
 const AGO = /^(\d+)(m|h|d)$/u;
 const AGO_MS = { m: 60_000, h: 3_600_000, d: 86_400_000 };
 const dayOf = (word, zone, now, span) => {

package/dist/query/index.d.ts

@@ -2,7 +2,7 @@
  * One query language for every list: Lucene syntax over the entity's own fields. The parser is a port of
  * Lucene 9.12.3's; the fields come from the entity schema; `evaluate` is a test oracle, never a list filter.
  */
-export { type DateRange, dateEndpoint, dateRange, dayBoundary, timezoneOf } from "./dates.js";
+export { type DateRange, dateEndpoint, dateRange, dayBoundary, timezoneOf, wallTime, zonedMoment } from "./dates.js";
 export { type EvaluateOptions, evaluate } from "./evaluate.js";
 export { FIELD_TYPES, type FieldAnnotations, type FieldSpec, type FieldType, OPERATORS_BY_TYPE, QUERY_BACKENDS, type QueryBackend, type QueryRegistry, queryFieldsOf, } from "./fields.js";
 export { fieldsHelp, QUERY_SYNTAX } from "./help.js";

package/dist/query/index.js

@@ -2,7 +2,7 @@
  * One query language for every list: Lucene syntax over the entity's own fields. The parser is a port of
  * Lucene 9.12.3's; the fields come from the entity schema; `evaluate` is a test oracle, never a list filter.
  */
-export { dateEndpoint, dateRange, dayBoundary, timezoneOf } from "./dates.js";
+export { dateEndpoint, dateRange, dayBoundary, timezoneOf, wallTime, zonedMoment } from "./dates.js";
 export { evaluate } from "./evaluate.js";
 export { FIELD_TYPES, OPERATORS_BY_TYPE, QUERY_BACKENDS, queryFieldsOf, } from "./fields.js";
 export { fieldsHelp, QUERY_SYNTAX } from "./help.js";

package/dist/query/parser.d.ts

@@ -2,7 +2,9 @@ import { type QueryAst, type QueryContext } from "./types.js";
 export interface ParseOptions extends QueryContext {
     /** The field a bare word searches; `none` for a list, where a bare word is `query.bare-word`. */
     defaultField?: string;
+    /** Read `"a b"~N` as a phrase with `slop: N`; a caller that turns it on says what N counts. */
+    proximity?: boolean;
 }
-export declare const parseLucene: (text: string, { defaultField, ...context }?: ParseOptions) => QueryAst;
+export declare const parseLucene: (text: string, { defaultField, proximity, ...context }?: ParseOptions) => QueryAst;
 /** Bare terms eligible for forgiving retrieval; explicit syntax keeps strict semantics. */
 export declare const implicitTextTerms: (text: string) => Set<number>;

package/dist/query/parser.js

@@ -141,7 +141,7 @@ const regexHint = (text, at) => {
     const word = `${/[^\s()"]*$/u.exec(text.slice(0, at))?.[0] ?? ""}${/^[^\s()"]*/u.exec(text.slice(at))?.[0] ?? ""}`;
     return quoteHint(text, at) ?? `/ starts a regular expression; put the value in quotes: "${word}"`;
 };
-export const parseLucene = (text, { defaultField = "text", ...context } = {}) => {
+export const parseLucene = (text, { defaultField = "text", proximity = false, ...context } = {}) => {
     const fail = (reason, span, alternative) => queryError(reason, span, alternative ?? quoteHint(text, span.start), context);
     if (text.length > QUERY_LIMITS.bytes || new TextEncoder().encode(text).length > QUERY_LIMITS.bytes)
         fail("query.too-large", { start: 0, end: text.length });
@@ -290,6 +290,13 @@ export const parseLucene = (text, { defaultField = "text", ...context } = {}) =>
                 ...(implicit ? { implicit: true } : {}),
             });
         }
+        if (proximity && peek().kind === "~" && node.kind === "predicate" && node.operator === "phrase") {
+            take();
+            const distance = take();
+            if (distance.kind !== "number" || !/^\d+$/u.test(distance.raw))
+                fail("query.invalid-syntax", distance.span, 'write the distance as a whole number: "a b"~3');
+            node = { ...node, slop: Number(distance.raw), span: { start: node.span.start, end: distance.span.end } };
+        }
         if (peek().kind === "~")
             fail("query.unsupported-operator", peek().span, node.kind === "predicate" && node.operator === "phrase"
                 ? "proximity (~) is not supported — drop the ~ for the exact phrase, or join the words with AND"

package/dist/query/types.d.ts

@@ -21,6 +21,8 @@ export interface Predicate {
     span: Span;
     /** A bare word, under no field. */
     implicit?: true;
+    /** `"a b"~N`, read only when the parser is asked to: how far apart the phrase's words may be. */
+    slop?: number;
 }
 export type QueryNode = Predicate | {
     kind: "boolean";

package/dist/query/types.js

@@ -16,6 +16,7 @@ const predicateSchema = v.object({
     upper_inclusive: v.optional(v.boolean()),
     span: spanSchema,
     implicit: v.optional(v.literal(true)),
+    slop: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
 });
 export const queryNodeSchema = v.variant("kind", [
     predicateSchema,

package/dist/standards/fields.js

@@ -4,7 +4,7 @@ const fieldRuleSchema = v.strictObject({ id: word, rule: text });
 export const defineFieldRules = (input) => parseRegistry("output field rules", v.array(fieldRuleSchema), input, (rules) => duplicates(rules.map((rule) => rule.id)).map((id) => `"${id}" is listed twice`));
 export const FIELD_RULES = defineFieldRules([
     { id: "envelope", rule: "every JSON answer is one object: a list `{items, page, …}`, one thing `{item, …}`" },
-    { id: "time", rule: "a time is an ISO 8601 string with a zone, never epoch milliseconds" },
+    { id: "time", rule: "a time is an ISO 8601 string in UTC, ending in `Z`, never epoch milliseconds" },
     { id: "duration", rule: "a length of time is a number of milliseconds in a key ending in `_ms`" },
     { id: "ref", rule: "a stored thing is named by `ref`; a message's `ref` value is its locator" },
     { id: "snake-case", rule: "keys are snake_case words, no abbreviations a reader has to decode" },

package/dist/standards/log.d.ts

@@ -7,7 +7,7 @@ export declare const LOG_SEVERITIES: readonly ["trace", "debug", "info", "warn",
  * (https://opentelemetry.io/docs/specs/otel/compatibility/logging_trace_context/); `run_id` and `command` are ours.
  */
 export declare const logRecordSchema: v.StrictObjectSchema<{
-    readonly time: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time with a zone">]>;
+    readonly time: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
     readonly severity: v.PicklistSchema<readonly ["trace", "debug", "info", "warn", "error", "fatal"], undefined>;
     /** The registered event id, `provider.request.failed`: never a sentence, so never content. */
     readonly body: v.StringSchema<undefined>;

package/dist/standards/output.d.ts

@@ -1,7 +1,7 @@
 import * as v from "valibot";
 /** At most two next steps per answer: the one to take, then one alternative. */
 export declare const MAX_NEXT_STEPS = 2;
-export declare const isoTime: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time with a zone">]>;
+export declare const isoTime: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
 /** The typed name of a stored thing, `msg:telegram/1/2/3` or `note:42`: what every other command takes. */
 export declare const reference: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
 export declare const nextStepSchema: v.VariantSchema<"kind", [v.StrictObjectSchema<{
@@ -65,6 +65,11 @@ export declare const metaSchema: v.StrictObjectSchema<{
         readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
     }, undefined>, undefined>, undefined>;
     readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+    readonly window: v.OptionalSchema<v.StrictObjectSchema<{
+        readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+    }, undefined>, undefined>;
 }, undefined>;
 export declare const listEnvelopeSchema: <T extends v.GenericSchema>(item: T) => v.StrictObjectSchema<{
     readonly items: v.ArraySchema<T, undefined>;
@@ -132,6 +137,11 @@ export declare const listEnvelopeSchema: <T extends v.GenericSchema>(item: T) =>
             readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly window: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+            readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        }, undefined>, undefined>;
     }, undefined>;
 }, undefined>;
 export declare const itemEnvelopeSchema: <T extends v.GenericSchema>(item: T) => v.StrictObjectSchema<{
@@ -189,6 +199,11 @@ export declare const itemEnvelopeSchema: <T extends v.GenericSchema>(item: T) =>
             readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        readonly window: v.OptionalSchema<v.StrictObjectSchema<{
+            readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+            readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        }, undefined>, undefined>;
     }, undefined>;
 }, undefined>;
 export type NextStep = v.InferOutput<typeof nextStepSchema>;

package/dist/standards/output.js

@@ -3,7 +3,7 @@ import { errorCodes } from "../errors.js";
 import { dottedId, text } from "./registry.js";
 /** At most two next steps per answer: the one to take, then one alternative. */
 export const MAX_NEXT_STEPS = 2;
-export const isoTime = v.pipe(v.string(), v.isoTimestamp("an ISO 8601 time with a zone"));
+export const isoTime = v.pipe(v.string(), v.isoTimestamp("an ISO 8601 time in UTC"), v.endsWith("Z", "an ISO 8601 time in UTC, ending in `Z`"));
 /** The typed name of a stored thing, `msg:telegram/1/2/3` or `note:42`: what every other command takes. */
 export const reference = v.pipe(v.string(), v.regex(/^[a-z]+:\S+$/, "a reference such as `note:42`"));
 export const nextStepSchema = v.variant("kind", [
@@ -65,6 +65,8 @@ export const metaSchema = v.strictObject({
     complete: v.boolean(),
     issues: v.optional(v.array(issueSchema)),
     truncated: v.optional(v.boolean()),
+    timezone: v.optional(text),
+    window: v.optional(v.strictObject({ since: v.optional(isoTime), until: v.optional(isoTime) })),
 });
 const nextSteps = v.optional(v.pipe(v.array(nextStepSchema), v.maxLength(MAX_NEXT_STEPS)));
 export const listEnvelopeSchema = (item) => v.strictObject({

package/dist/testing/index.js

@@ -22,7 +22,7 @@ export const fakeClock = (startMs = 0) => {
     return {
         waits,
         clock: () => elapsed,
-        now: () => new Date(startMs + elapsed),
+        now: () => new Date(elapsed),
         sleep: async (ms, signal, reason) => {
             if (signal?.aborted)
                 throw new DOMException("The operation was aborted.", "AbortError");

package/docs/standards/README.md

@@ -1,7 +1,7 @@
 # WireCat CLI standards
 
 This handbook holds the rules every WireCat CLI follows: tools, layout, commands, output, MCP, accounts,
-permissions, architecture, tests, security, documents, releases and CI. Read this page first. Then read the page
+permissions, architecture, time, tests, security, documents, releases and CI. Read this page first. Then read the page
 for the area you are about to change.
 
 It ships in the `@wirecat/cli-base` package. A CLI that depends on cli-base has it at
@@ -40,6 +40,7 @@ rules it keeps. A new CLI is ready for its first release when every check under
 | [Documents](docs.md) | `DOC` | 20 | User pages and developer pages, generated pages, current facts, changelog |
 | [Releases](releases.md) | `REL` | 16 | `bin/release`, the release lock, versions, release reports, trusted publishing |
 | [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |
+| [Time](time.md) | `TIME` | 6 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone |
 | [Style](style.md) | `STYLE` | 10 | Comments, TypeScript habits, commit messages |
 | [New CLI](new-cli.md) | — | — | The checklist for starting a new CLI |
 

package/docs/standards/output.md

@@ -80,7 +80,9 @@ JSON Schema 2020-12.
 
 - **Why:** `run_id` finds the run later, and `complete` says whether the answer can be trusted as whole.
 - **Enforced by:** review only.
-- **Example:** `{ run_id, duration_ms, accounts?, complete, issues?, truncated? }`. `complete: false` with
+- **Example:** `{ run_id, duration_ms, accounts?, complete, issues?, truncated?, timezone?, window? }`. `timezone`
+  names the zone a time without one was read or shown in, and `window` the UTC bounds a date filter used
+  ([Time](time.md)). `complete: false` with
   `issues: [{ code, reason?, source }]` says a source failed or was skipped. `truncated` says a size cap cut the
   answer. Neither one means another page exists: that is `page.has_more`.
 - **Exceptions:** none.
@@ -147,7 +149,7 @@ JSON Schema 2020-12.
 
 - **Why:** a caller must not guess whether `0` means "none" or "unknown".
 - **Enforced by:** `nullable-list`.
-- **Example:** a time is an ISO 8601 string with a zone, never epoch milliseconds. A length of time is a number of
+- **Example:** a time is an ISO 8601 string in UTC, ending in `Z`, never epoch milliseconds ([Time](time.md)). A length of time is a number of
   milliseconds in a key ending in `_ms`. A stored thing is named by `ref`. A key that is absent was not asked for or
   is not known. `null` is known to have no value. `[]` is known to be empty, never `null`. `0` is measured, never a
   stand-in for unknown.

package/docs/standards/time.md

@@ -0,0 +1,97 @@
+# Time
+
+## Scope
+
+How a CLI keeps, exchanges, reads and shows a moment in time: UTC inside, a zone only at the edges.
+
+Rule ids on this page are `WC-TIME-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+Related pages: how a time is written in an answer, next to durations and empty values, is in [Output](output.md)
+(`WC-OUT-13`); the store and its migrations are in [Store](store.md); the test sandbox is in [Testing](testing.md).
+
+### Words used here
+
+- **Edge:** a place where a time enters without a zone (a typed date, a file name, a provider field) or leaves for
+  a person to read (human text output).
+- **Zone in use:** the `--timezone` flag when given, else the zone a setting names, else the computer's IANA zone.
+
+## Rules
+
+### WC-TIME-1 · Store every time in UTC
+
+Every time in a database, cache, cursor, receipt, manifest or exported file is UTC: an ISO 8601 string ending in
+`Z`, or epoch milliseconds. Never local wall time, never an offset other than zero.
+
+- **Why:** a stored time read on another computer, or after the owner travels, must mean the same moment.
+- **Enforced by:** review only.
+- **Example:** `sent_at INTEGER` holding `1792591380000`, or `"2026-10-21T14:03:00.000Z"`.
+- **Exceptions:** a column that already holds UTC in another unambiguous form (SQLite's `YYYY-MM-DD HH:MM:SS` from
+  `CURRENT_TIMESTAMP`, epoch seconds) stays until its table next migrates; its value still leaves as `WC-TIME-2`
+  says. A column that may hold local time gets a forward-only migration, or a proof from history that every writer
+  wrote UTC.
+- **Applies to:** all CLIs, cli-core and cli-base. **Since:** cli-base 0.48.0. **Rulings:** NEED-1592.
+
+### WC-TIME-2 · Exchange every time in UTC, and add a local time only beside it
+
+JSON, JSONL and MCP output carry each time as an ISO 8601 string ending in `Z`. A display zone may add a second key,
+`<key>_local`, with the offset of the zone in use, and `meta.timezone` then names that zone. The local key never
+replaces the UTC one.
+
+- **Why:** an agent compares and sorts times from many CLIs; one form, in one zone, needs no guessing.
+- **Enforced by:** review only.
+- **Example:** `{ "sent_at": "2026-10-21T14:03:00.000Z", "sent_at_local": "2026-10-21T16:03:00.000+02:00" }` with
+  `"meta": { "timezone": "Europe/Madrid", … }`.
+- **Exceptions:** a provider's own text kept as it came (a mail `Date:` header) goes under `provider_metadata`.
+- **Applies to:** all CLIs. **Since:** cli-base 0.48.0. **Rulings:** none.
+
+### WC-TIME-3 · Read a time that has no zone in the zone in use, and say which zone that was
+
+A typed date, a file name or a provider field without a zone is read in the zone in use. The answer says that zone:
+`meta.timezone` in machine mode, a short line in human text.
+
+- **Why:** a silent default turns a wall-clock time into the wrong moment; zm stored 111 meetings two hours late when
+  file names were read as UTC.
+- **Enforced by:** review only.
+- **Example:** `zm import 2026-10-21_1603_standup.vtt` on a computer in `Europe/Madrid` stores `14:03Z`, and says
+  "file times read in Europe/Madrid".
+- **Exceptions:** a provider documented to send UTC without a marker is read as UTC, with a link to that
+  documentation next to the code. A local time that daylight saving makes ambiguous or nonexistent is refused, never
+  guessed.
+- **Applies to:** all CLIs. **Since:** cli-base 0.48.0. **Rulings:** NEED-1592.
+
+### WC-TIME-4 · Show times to a person in the zone in use, and say which zone
+
+- **Why:** a person reads wall-clock time; a UTC time shown without a word reads as local.
+- **Enforced by:** review only.
+- **Example:** `messages list` prints `16:03` and ends with `times in Europe/Madrid`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.48.0. **Rulings:** none.
+
+### WC-TIME-5 · A date with no time covers the whole local day, and the answer gives the window in UTC
+
+`--since-time 2026-09-01` starts at local midnight of the zone in use; `--until-time 2026-09-01` ends at the next
+local midnight. The answer gives the window it used, in UTC.
+
+- **Why:** "messages of 1 September" means the owner's day, not the UTC day, which starts hours earlier or later.
+- **Enforced by:** review only.
+- **Example:** in `Asia/Vladivostok`, `--since-time 2026-09-01` gives `meta.window.since` = `2026-08-31T14:00:00.000Z`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.48.0. **Rulings:** none.
+
+### WC-TIME-6 · Run the tests in a zone that is not UTC, and prove stored values do not depend on it
+
+The shared `node-ci.yml` runs `test:coverage` with `TZ=Asia/Vladivostok` (UTC+10, no daylight saving). Each
+repository that stores times has a test that writes the same input under two zones and gets identical stored values.
+
+- **Why:** a suite that runs only in UTC passes for every bug on this page.
+- **Enforced by:** `node-ci.yml`.
+- **Example:** set `process.env.TZ` to `Asia/Vladivostok`, then to `America/Los_Angeles`, write the same message each
+  time, and compare the rows. Node applies a changed `TZ` at once.
+- **Exceptions:** a repository that keeps no time skips the second test.
+- **Applies to:** all CLIs, cli-core and cli-base. **Since:** cli-base 0.48.0. **Rulings:** none.
+
+## Sources
+
+- The owner's ruling of 21.10.2026: every time is stored and exchanged in UTC, in every repository.
+- NEED-1592: zm reads file name times in the computer's zone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.47.5",
+  "version": "0.49.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",