monday-cli 0.2.0 → 0.3.0

package/dist/api/item-history-projection.d.ts

@@ -0,0 +1,919 @@
+/**
+ * Per-item activity-log + comment-thread projection for the v0.3-M24
+ * `monday item history <iid>` verb (`cli-design.md` §13 v0.3 entry).
+ *
+ * **What `monday item history` answers:** "show me every change +
+ * comment on this item, chronologically, in one stream" — without
+ * the agent walking `activity_logs` AND `updates` separately and
+ * folding by `created_at` by hand. Two Monday surfaces feed the
+ * stream:
+ *
+ *   1. `boards(ids:) { activity_logs(item_ids:, from:, to:,
+ *      page:, limit:) }` — Monday's per-board activity log,
+ *      filtered to the target item via `item_ids` AND additionally
+ *      filtered WALKER-SIDE (post-fetch, before projection) to
+ *      `entity = 'pulse'` (the `item_ids` arg ALONE does NOT
+ *      exclude board-scoped events; empirical-probe finding
+ *      2026-05-11). Page-numbered pagination (Monday's native
+ *      shape; `--activity-logs-page <n>` / `--limit <n>` flags
+ *      surface it).
+ *   2. `items(ids:) { updates(limit:, page:) { ... replies { ...
+ *      } } }` — Monday's comment thread (top-level updates +
+ *      nested replies). Projected into synthesized
+ *      `update_posted` + `update_replied` event-objects so the
+ *      merged stream is uniform.
+ *
+ * The merge projector orders the unified stream by `created_at`
+ * ascending; ties break by `id` for deterministic output across
+ * runs.
+ *
+ * **Decision 2 closure** (`a1f3025`, M24-prep empirical probe pass
+ * 2026-05-11; full findings at v0.3-plan §8 Decision 2 closure).
+ * Three load-bearing findings from the live probe against a real
+ * workspace + 19 captured `activity_logs` rows on a production
+ * board:
+ *
+ *   - **Schema field name is `event`, NOT `kind`.** Monday's
+ *     `ActivityLogType` exposes 7 fields per the introspection
+ *     probe (all NON_NULL String): `account_id`, `created_at`,
+ *     `data`, `entity`, `event`, `id`, `user_id`. The v0.3-plan
+ *     §3 M24 description used "kind" as the synonym; the projector
+ *     keeps `kind` as the CLI agent-facing discriminator (domain-
+ *     neutral) but maps it 1:1 from the wire's `event` slot.
+ *   - **Observed event taxonomy (production data; 19 rows on one
+ *     board over 30 days; NOT exhaustive):** `create_column`
+ *     (10×), `update_column_value` (4×; the dominant ITEM-SCOPED
+ *     event), `create_group` (2×), `board_workspace_id_changed`
+ *     (1×), `update_board_name` (1×), `update_board_nickname`
+ *     (1×). The `update_column_value` payload carries `column_id`
+ *     + `column_type` + `value` + `previous_value` + `textual_value`
+ *     + `pulse_id` + `pulse_name`; `previous_value` is sometimes
+ *     `{}` for first-set events (decoded defensively as
+ *     "previously-unset" — preserved as `{}` on the projected
+ *     event so agents distinguish "first set" from "no prior
+ *     value tracked"). The runtime projector applies one level
+ *     of nested-JSON unwrap on `value` / `previous_value` so the
+ *     before/after slots carry structured payloads (e.g.
+ *     `{label, index}` for status, ISO string for date) rather
+ *     than opaque JSON-string scalars.
+ *   - **`entity` field discriminates item-scoped from board-scoped
+ *     events.** Observed values: `pulse` (4×; item-scoped) and
+ *     `board` (15×; board-scoped). The walker filters
+ *     `entity = 'pulse'` to drop board-level noise (column
+ *     additions, group creation, board renames) that aren't part
+ *     of the item's history. **The `item_ids` filter alone is
+ *     INSUFFICIENT** — passing it does NOT exclude board-scoped
+ *     events from the response.
+ *
+ * **Eventual-consistency caveat (carry to cli-design §13 v0.3
+ * entry).** Monday's `activity_logs` has an empirically-measured
+ * propagation lag **>30s** on freshly-edited boards. The verb's
+ * help text MUST NOT promise immediate-history for newly-modified
+ * items; agents polling `monday item history` after a write should
+ * wait at least 30s before expecting their write to surface.
+ *
+ * **Update + Reply shapes (also pinned by the probe).** `Update`
+ * carries 16 fields per introspection; the projector projects only
+ * the load-bearing ones: `id` (NON_NULL ID), `body` (NON_NULL
+ * String), `text_body` (nullable String), `created_at` (nullable
+ * `Date`), `creator_id` (nullable String), `replies` (LIST[Reply!]
+ * with the list itself nullable; items non-null). `Reply` carries
+ * its OWN `kind: String!` field — separate taxonomy from
+ * `activity_logs.event` — and the projector surfaces it under the
+ * synthesized `update_replied` event's `reply_kind` slot.
+ *
+ * **Runtime composition.** {@link fetchItemHistory} drives the
+ * two-source walker; {@link projectActivityLogRow},
+ * {@link projectUpdateRow}, and {@link projectReplyRow} are the
+ * per-row projectors (the activity-log projector reads the wire
+ * `data` JSON, dispatches on `event`, and applies a one-level
+ * nested-JSON unwrap on `update_column_value`'s `value` /
+ * `previous_value` so agents see the structured payload — e.g.
+ * `{label, index}` for status, ISO string for date — rather than
+ * an opaque JSON-string). The walker filters
+ * `entity === ITEM_SCOPED_ENTITY` walker-side (single source of
+ * truth per Decision 2 closure; projector does NOT re-filter).
+ *
+ * **Streaming reuse.** Per the v0.3-plan §3 M24 deliverable, the
+ * verb reuses `startNdjsonStream` (R52) when `--stream` is on; the
+ * trailer meta carries `{has_more, total_returned, complexity,
+ * source}` per cli-design §6.3 + the symmetric page-numbered
+ * per-source `activity_logs.last_page` + `updates.last_page` slots
+ * (both 1-indexed; `null` when the walker exhausted that source) so
+ * agents resuming a partial walk re-issue with the per-source
+ * `last_page + 1`. No cursor surface at v0.3 — both sources
+ * paginate page-numbered.
+ */
+import { z } from 'zod';
+import type { MondayClient } from './client.js';
+import type { Complexity, Warning } from '../utils/output/envelope.js';
+import type { ItemId } from '../types/ids.js';
+/**
+ * Wire field name on `ActivityLogType` that discriminates
+ * item-scoped (`pulse`) from board-scoped (`board`) events per the
+ * Decision 2 closure entity-filter finding. The walker filters on
+ * this constant before handing rows to the projector; the projector
+ * itself does NOT re-filter (single source of truth at the walker
+ * layer).
+ */
+export declare const ITEM_SCOPED_ENTITY: "pulse";
+/**
+ * Default per-page slice for `activity_logs(limit: <n>, page: <n>)`.
+ * Monday's `activity_logs` resolver caps the per-call slice at 10000;
+ * the CLI default of 100 keeps the per-call latency below the per-
+ * page budget while letting `--limit <n>` cap the aggregate. Mirrors
+ * the v0.1 `DEFAULT_PAGE_SIZE` of 100.
+ */
+export declare const DEFAULT_HISTORY_PAGE_SIZE = 100;
+/**
+ * Hard cap on `--limit` for `activity_logs` per-call slice. Monday's
+ * documented ceiling is 10000; the CLI mirrors it so the parse
+ * boundary rejects over-large requests with `usage_error` rather
+ * than letting Monday's server-side rejection surface as
+ * `validation_failed` mid-walk.
+ */
+export declare const HARD_CAP_HISTORY_PAGE_SIZE = 10000;
+/**
+ * Stage-1 GraphQL document — `activity_logs` per-page slice.
+ *
+ * Per the Decision 2 closure introspection finding,
+ * `ActivityLogType` has 7 NON_NULL String fields. The projector
+ * reads all 6 non-`account_id` slots (`account_id` carries no
+ * item-history signal — every row in a single-account CLI session
+ * shares it).
+ *
+ * **`item_ids` filter is necessary BUT NOT SUFFICIENT.** Per the
+ * probe finding, board-scoped events (entity = 'board') leak
+ * through even with `item_ids` set. The WALKER
+ * ({@link fetchItemHistory}) filters `row.entity ===
+ * ITEM_SCOPED_ENTITY` immediately after the page parses and
+ * BEFORE handing rows to {@link projectActivityLogRow}. The
+ * projector itself does NOT re-filter — single source of truth at
+ * the walker layer per Decision 2 closure. Server-side filtering
+ * would require a custom GraphQL middleware Monday doesn't expose;
+ * filtering later than the walker would force row-shaping code to
+ * know about the entity discriminator, which belongs to the
+ * walker's "which rows are part of THIS item's history" question,
+ * not the projector's "how do I shape this row's payload" question.
+ *
+ * Monday's `activity_logs(item_ids:, from:, to:, page:, limit:)`
+ * signature accepts ISO-8601 timestamps for `from` / `to` per the
+ * sibling `created_at` ISO8601DateTime scalar; nullable on both
+ * sides so a partial range (`--since` only / `--until` only) maps
+ * cleanly to omitting the absent slot.
+ */
+export declare const ACTIVITY_LOGS_QUERY = "\n  query ItemHistoryActivityLogs(\n    $bid: [ID!]!,\n    $iid: [ID!]!,\n    $from: ISO8601DateTime,\n    $to: ISO8601DateTime,\n    $page: Int!,\n    $limit: Int!\n  ) {\n    boards(ids: $bid) {\n      id\n      activity_logs(\n        item_ids: $iid,\n        from: $from,\n        to: $to,\n        page: $page,\n        limit: $limit\n      ) {\n        id\n        event\n        entity\n        user_id\n        created_at\n        data\n      }\n    }\n  }\n";
+/**
+ * Stage-2 GraphQL document — `items(ids:) { updates(...) }` for
+ * the comment-thread source.
+ *
+ * Per the Decision 2 closure introspection finding, `Update` has
+ * 16 fields; the projector selects only the load-bearing slots
+ * (id / body / text_body / created_at / creator_id / replies +
+ * the Reply sub-selection). Other fields (`likes`, `pinned_to_top`,
+ * `viewers`, `assets`) are not part of the item-history surface in
+ * v0.3; a v0.4 follow-up may extend the projection under the
+ * `update_posted` event's `after` slot if those fields become
+ * agent-useful (envelope-additive per §6.1).
+ *
+ * **Update.created_at + Reply.created_at are nullable** per the
+ * probe introspection (both fields are `SCALAR/Date`, nullable).
+ * The projector substitutes `Update.edited_at` (NON_NULL Date) as
+ * the chronological key when `created_at` is null — silent
+ * projection behaviour (NOT a warning surface; the substitution is
+ * deterministic + agents observing a null-`created_at` Update on
+ * the wire reproduce the same merge order on a re-walk). v0.3's
+ * `warnings[]` shape is `unknown_event_kind` only; adding a
+ * `synthesized_created_at` warning is a v0.4 envelope-additive
+ * extension if the substitution turns out to be agent-visible in
+ * practice.
+ *
+ * Monday's `updates(limit:, page:)` signature is page-numbered;
+ * the projector exposes `--updates-page <n>` so the two sources
+ * paginate independently (activity_logs and updates have their own
+ * page counters; merging them onto a single `--page <n>` flag would
+ * conflate two different denominators).
+ */
+export declare const UPDATES_QUERY = "\n  query ItemHistoryUpdates(\n    $iid: [ID!]!,\n    $page: Int!,\n    $limit: Int!\n  ) {\n    items(ids: $iid) {\n      id\n      updates(limit: $limit, page: $page) {\n        id\n        body\n        text_body\n        created_at\n        edited_at\n        creator_id\n        replies {\n          id\n          kind\n          body\n          text_body\n          created_at\n          updated_at\n          creator_id\n        }\n      }\n    }\n  }\n";
+/**
+ * Wire-shape schema for an `ActivityLogType` row (Decision 2 closure
+ * introspection finding — 7 NON_NULL String fields). `.loose()` so
+ * future Monday surface extensions don't break the parse — the
+ * projector reads only the fields it knows about and forward-compat
+ * fields pass through to no consumer.
+ */
+export declare const rawActivityLogRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    event: z.ZodString;
+    entity: z.ZodString;
+    user_id: z.ZodString;
+    created_at: z.ZodString;
+    data: z.ZodString;
+}, z.core.$loose>;
+export type RawActivityLogRow = z.infer<typeof rawActivityLogRowSchema>;
+/**
+ * Wire-shape schema for one `Reply` row inside `Update.replies`.
+ * Per the Decision 2 closure introspection finding, `Reply.id` +
+ * `Reply.body` + `Reply.kind` are NON_NULL; `Reply.created_at` is
+ * nullable Date; `Reply.creator_id` is nullable String.
+ *
+ * **`Reply.kind` is a separate taxonomy from
+ * `activity_logs.event`.** Reply's kind discriminates comment-thread
+ * reply types (e.g., a regular reply vs a system-generated reply);
+ * activity_logs's event discriminates board-level change types. The
+ * projector surfaces `Reply.kind` under the synthesized
+ * `update_replied` event's `reply_kind` slot so agents can
+ * introspect it without confusion.
+ */
+export declare const rawReplyRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    body: z.ZodString;
+    kind: z.ZodString;
+    text_body: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodNullable<z.ZodString>;
+    creator_id: z.ZodNullable<z.ZodString>;
+}, z.core.$loose>;
+export type RawReplyRow = z.infer<typeof rawReplyRowSchema>;
+/**
+ * Wire-shape schema for one `Update` row. `created_at` is nullable
+ * per the probe introspection (Date scalar, optional); the
+ * projector substitutes `edited_at` (NON_NULL Date) when
+ * `created_at` is absent.
+ */
+export declare const rawUpdateRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    body: z.ZodString;
+    text_body: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodNullable<z.ZodString>;
+    edited_at: z.ZodString;
+    creator_id: z.ZodNullable<z.ZodString>;
+    replies: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        body: z.ZodString;
+        kind: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodNullable<z.ZodString>;
+        updated_at: z.ZodNullable<z.ZodString>;
+        creator_id: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type RawUpdateRow = z.infer<typeof rawUpdateRowSchema>;
+/**
+ * **`update_column_value`** — the dominant ITEM-SCOPED activity-log
+ * event per the Decision 2 closure observed-events list (4× of 19
+ * rows; the only item-scoped kind in the sample). Carries the
+ * column-edit before / after payload.
+ *
+ * Schema slots:
+ *   - `column_id` + `column_type` from the wire `data` payload
+ *     (always present per the probe).
+ *   - `before` + `after` as `z.unknown()` slots carrying the
+ *     parsed `previous_value` / `value` JSON. The runtime
+ *     projector applies one level of nested-JSON unwrap so
+ *     agents see structured payloads (e.g. `{label, index}` for
+ *     status, ISO string for date) rather than opaque JSON-
+ *     string scalars. `z.unknown()` keeps the schema permissive
+ *     so future Monday column types don't break the parse —
+ *     agents introspect via `column_type` and the runtime
+ *     payload.
+ *   - `textual_value` — Monday's human-readable rendering of the
+ *     new value (always present per the probe; nullable for
+ *     defensive forward-compat with future column types Monday
+ *     may not provide a textual rendering for).
+ *   - `pulse_id` + `pulse_name` — item identity for cross-board
+ *     consumers; nullable for subitem variants where the parent
+ *     identification carries the load. `pulse_id` ships as an
+ *     unquoted JSON number on the wire (probe-confirmed); the
+ *     runtime projector stringifies it via
+ *     `readNullableIdField` (Codex impl round-2 P2-1).
+ */
+export declare const updateColumnValueEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"update_column_value">;
+    column_id: z.ZodString;
+    column_type: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+    textual_value: z.ZodNullable<z.ZodString>;
+    pulse_id: z.ZodNullable<z.ZodString>;
+    pulse_name: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const createColumnEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"create_column">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const createGroupEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"create_group">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const updateBoardNameEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"update_board_name">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const updateBoardNicknameEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"update_board_nickname">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const boardWorkspaceIdChangedEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"board_workspace_id_changed">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>;
+/**
+ * **`update_posted`** — synthesized event for a top-level comment
+ * on the item. The projector maps `Update` rows from the
+ * comment-thread source into this shape; activity_logs does NOT
+ * surface comments as its own events, so the cross-source merge
+ * is what unifies them.
+ *
+ * - `before: null` — comments are append-only events (no prior
+ *   state).
+ * - `after.body` — `Update.body` (NON_NULL String per the probe).
+ * - `after.text_body` — `Update.text_body` (nullable; Monday's
+ *   plain-text rendering of the rich-text body).
+ * - `after.reply_count` — count of `Update.replies` after the
+ *   wire-side null-coalesce (Monday returns `null` for "no
+ *   replies known"; the projector folds to `0` for agent
+ *   ergonomics — see `mergeByCreatedAt` semantics).
+ */
+export declare const updatePostedEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"update_posted">;
+    before: z.ZodNull;
+    after: z.ZodObject<{
+        body: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+        reply_count: z.ZodNumber;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * **`update_replied`** — synthesized event for one reply within a
+ * comment thread. The projector emits ONE event per `Reply` row;
+ * the parent `Update.id` lands on `parent_update_id` so agents can
+ * reconstruct thread context without a second round-trip.
+ *
+ * `reply_kind` carries `Reply.kind` (NON_NULL String per the
+ * probe — a SEPARATE taxonomy from `activity_logs.event`). Pre-
+ * flight pins this as `z.string()` (open enum) per the same
+ * forward-compat policy as M23 favorites' `object.type` field —
+ * Monday may extend Reply.kind with new variants without breaking
+ * the parse.
+ */
+export declare const updateRepliedEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"update_replied">;
+    parent_update_id: z.ZodString;
+    reply_kind: z.ZodString;
+    before: z.ZodNull;
+    after: z.ZodObject<{
+        body: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * **`unknown`** — fallback variant for an `activity_logs.event`
+ * value the projector doesn't recognise. Carries the raw wire
+ * `event` slot (so agents see the unrecognised string) + the raw
+ * `entity` slot (so the walker filter discrepancy is visible) +
+ * the raw parsed `data` JSON under `after` (so a future-extension
+ * consumer can reproject without a second wire call). `before` is
+ * `null` for uniform shape with the synthesized comment-event
+ * variants (`update_posted` / `update_replied`) which also pin
+ * `before: null` for their append-only-events semantics — the
+ * `unknown` variant similarly has no meaningful "before" since the
+ * projector by definition doesn't know how to extract the prior
+ * state from the wire payload (the typed variants are the place
+ * that knowledge lives). Agents wanting to introspect the raw
+ * payload read `after` (the full parsed `data` JSON) alongside
+ * `event` + `entity` for routing.
+ *
+ * Surfaces alongside a `warnings[]` entry of code
+ * `unknown_event_kind` (per {@link buildUnknownEventKindWarning})
+ * so agents introspect the projector's coverage gap without parsing
+ * the events list for `kind === 'unknown'` themselves.
+ *
+ * Per Decision 2 closure: this variant is the registry-stable
+ * surface for forward-compat with Monday's expanding event
+ * taxonomy. The 29-error-code registry stays AT 29 — the unknown-
+ * event-kind surface is a `warnings[]` shape, NOT a new
+ * `error.code` entry.
+ */
+export declare const unknownEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"unknown">;
+    event: z.ZodString;
+    entity: z.ZodString;
+    before: z.ZodNull;
+    after: z.ZodUnknown;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The projected per-event discriminated union — the contract surface
+ * for `monday item history`. Agents read `kind` to route per-variant
+ * handling. Adding a new variant is non-breaking (envelope-additive
+ * per §6.1); renaming or removing one is the SemVer-major boundary.
+ *
+ * **Variant count: 9** (1 item-scoped activity-log + 5 board-scoped
+ * activity-log variants kept for parser-roundtrip + 2 synthesized
+ * comment-thread variants + 1 unknown fallback). The Decision 2
+ * closure observed-events list capped the activity-log variants at
+ * 6; the synthesized + fallback variants are the projector's own
+ * contract.
+ *
+ * **Decision 2 ratification.** The discriminator field name `kind`
+ * maps 1:1 from Monday's wire `ActivityLogType.event` field
+ * (schema field-name drift); the variants enumerate the observed
+ * production taxonomy + the `unknown` fallback for forward-compat.
+ */
+export declare const historyEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"update_column_value">;
+    column_id: z.ZodString;
+    column_type: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+    textual_value: z.ZodNullable<z.ZodString>;
+    pulse_id: z.ZodNullable<z.ZodString>;
+    pulse_name: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"create_column">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"create_group">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"update_board_name">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"update_board_nickname">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"board_workspace_id_changed">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"update_posted">;
+    before: z.ZodNull;
+    after: z.ZodObject<{
+        body: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+        reply_count: z.ZodNumber;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"update_replied">;
+    parent_update_id: z.ZodString;
+    reply_kind: z.ZodString;
+    before: z.ZodNull;
+    after: z.ZodObject<{
+        body: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unknown">;
+    event: z.ZodString;
+    entity: z.ZodString;
+    before: z.ZodNull;
+    after: z.ZodUnknown;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>], "kind">;
+export type HistoryEvent = z.infer<typeof historyEventSchema>;
+/**
+ * The top-level command output schema — `data` is the chronologically-
+ * merged event array. Mirrors M23's `crossBoardSearchOutputSchema`
+ * (a flat array of typed rows; no top-level metadata in `data`).
+ */
+export declare const historyEventOutputSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"update_column_value">;
+    column_id: z.ZodString;
+    column_type: z.ZodString;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+    textual_value: z.ZodNullable<z.ZodString>;
+    pulse_id: z.ZodNullable<z.ZodString>;
+    pulse_name: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"create_column">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"create_group">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"update_board_name">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"update_board_nickname">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+    kind: z.ZodLiteral<"board_workspace_id_changed">;
+    before: z.ZodUnknown;
+    after: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"update_posted">;
+    before: z.ZodNull;
+    after: z.ZodObject<{
+        body: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+        reply_count: z.ZodNumber;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"update_replied">;
+    parent_update_id: z.ZodString;
+    reply_kind: z.ZodString;
+    before: z.ZodNull;
+    after: z.ZodObject<{
+        body: z.ZodString;
+        text_body: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unknown">;
+    event: z.ZodString;
+    entity: z.ZodString;
+    before: z.ZodNull;
+    after: z.ZodUnknown;
+    id: z.ZodString;
+    created_at: z.ZodString;
+    actor_id: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>], "kind">>;
+export type HistoryEventOutput = z.infer<typeof historyEventOutputSchema>;
+/**
+ * Warning surfaced when the projector encountered an
+ * `activity_logs.event` value not in the typed-variant set
+ * (`event` mapped to the `kind: 'unknown'` fallback). `details`
+ * carries the raw event + entity values so agents can extend the
+ * projector or file a follow-up.
+ *
+ * **NOT an `error.code` registry entry** per Decision 2 closure —
+ * §6.1 `warnings[]` shape only. The 29-stable-error-code registry
+ * stays at 29.
+ *
+ * **Aggregation semantics.** The projector emits ONE warning per
+ * unique `event` value observed in the merged stream (not per
+ * occurrence) — repeated `unknown` events of the same wire kind
+ * surface a single warning carrying `details.occurrence_count` so
+ * the warnings array stays bounded even on degenerate inputs.
+ */
+export interface UnknownEventKindWarning {
+    readonly code: 'unknown_event_kind';
+    readonly message: string;
+    readonly details: {
+        readonly event: string;
+        readonly entity: string;
+        readonly occurrence_count: number;
+        readonly hint: string;
+    };
+}
+export declare const unknownEventKindWarningSchema: z.ZodObject<{
+    code: z.ZodLiteral<"unknown_event_kind">;
+    message: z.ZodString;
+    details: z.ZodObject<{
+        event: z.ZodString;
+        entity: z.ZodString;
+        occurrence_count: z.ZodNumber;
+        hint: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * Builds an {@link UnknownEventKindWarning} from one observed
+ * unknown event + its occurrence count across the merged stream.
+ * **Real implementation** at pre-flight (pure helper; the warning
+ * shape is the contract surface).
+ *
+ * The hint forward-references the projector's extensibility point
+ * so agents have a concrete next step (vs a generic "unknown"
+ * message that requires reading the source).
+ */
+export declare const buildUnknownEventKindWarning: (event: string, entity: string, occurrenceCount: number) => UnknownEventKindWarning;
+/**
+ * Merges two pre-projected event streams (activity-log + comment-
+ * thread) into a single chronologically-ordered stream. **Real
+ * implementation** at pre-flight (pure helper).
+ *
+ * Ordering rules:
+ *   - Primary: `created_at` ascending (oldest first; matches
+ *     Monday's UI activity log + comment thread chronological
+ *     reading order).
+ *   - Tie-break: `id` (lexicographic) — deterministic across runs
+ *     even when two events share the exact same `created_at`
+ *     timestamp (Monday's resolver issues IDs in monotonic order
+ *     per source, so the tie-break preserves intra-source order).
+ *
+ * **Why merge here, not at the walker.** The two source walkers
+ * paginate independently (activity_logs page-numbered;
+ * updates page-numbered with a different denominator); merging at
+ * the walker would force coupled pagination on the streaming
+ * path. The projector merges the FULLY-DRAINED-PER-WALL-CLOCK-CAP
+ * lists — `fetchItemHistory` walks both sources to the `--since`
+ * / `--until` cap independently, then this helper merges.
+ *
+ * **Streaming semantics.** When `--stream` is on, the merge is
+ * NOT incremental — the entire `--since`-bounded slice must be
+ * resident to order it. The NDJSON stream emits the merged array
+ * per-item via the walker's `onItem` hook AFTER the merge
+ * completes; the trailer carries the per-source pagination state
+ * for resumption.
+ */
+export declare const mergeByCreatedAt: (activityEvents: readonly HistoryEvent[], commentEvents: readonly HistoryEvent[]) => readonly HistoryEvent[];
+/**
+ * Inputs to {@link projectActivityLogRow}.
+ */
+export interface ProjectActivityLogRowInputs {
+    readonly row: RawActivityLogRow;
+}
+/**
+ * Projects one wire `ActivityLogType` row into a typed
+ * {@link HistoryEvent}. Parses the wire `data` JSON, dispatches
+ * on `row.event`, and emits the matching typed variant. Unknown
+ * event kinds fall back to the `unknown` variant carrying the raw
+ * parsed `data` under `after`.
+ *
+ * The projector is the SINGLE per-row dispatch point; the walker
+ * delegates to it after the `entity === 'pulse'` filter (single
+ * source of truth at the walker layer per Decision 2 closure;
+ * projector does NOT re-filter).
+ *
+ * Per-`column_type` typed before/after for `update_column_value`:
+ * `value` and `previous_value` are passed through with one level
+ * of nested-JSON unwrap (Monday encodes nested values as JSON
+ * strings inside the outer `data` payload); each column type's
+ * concrete payload shape (e.g. status `{label, index}`, date ISO
+ * string, text raw string) flows through unchanged. Per Decision
+ * 2 closure: `previous_value: {}` is preserved as "previously-
+ * unset" rather than collapsed to `null` — agents distinguish
+ * the empty-object shape.
+ */
+export declare const projectActivityLogRow: (inputs: ProjectActivityLogRowInputs) => HistoryEvent;
+/**
+ * Inputs to {@link projectUpdateRow}.
+ */
+export interface ProjectUpdateRowInputs {
+    readonly row: RawUpdateRow;
+}
+/**
+ * Projects one wire `Update` row into a synthesized
+ * {@link HistoryEvent} of kind `update_posted` plus one
+ * `update_replied` event per `row.replies` entry (via
+ * {@link projectReplyRow}). Returns a flat array suitable for
+ * the merger.
+ *
+ * `Update.created_at` is nullable per Decision 2 closure probe
+ * findings; the projector substitutes `Update.edited_at`
+ * (NON_NULL) as the chronological key — silent projection
+ * behaviour, deterministic across re-walks.
+ *
+ * Replies are flat-mapped here (not at the walker) so the
+ * walker stays surface-symmetric with the activity_logs source
+ * (both project per-row → events). The merge projector orders
+ * the combined stream.
+ */
+export declare const projectUpdateRow: (inputs: ProjectUpdateRowInputs) => readonly HistoryEvent[];
+/**
+ * Inputs to {@link projectReplyRow}. The `parentUpdateId` slot
+ * wires the synthesized event's `parent_update_id` so agents
+ * reconstruct thread context; the `parentCreatedAt` slot supplies
+ * the timestamp fallback when both reply timestamps are null
+ * (defensive against Monday's nullable Reply.created_at +
+ * Reply.updated_at combination).
+ */
+export interface ProjectReplyRowInputs {
+    readonly row: RawReplyRow;
+    readonly parentUpdateId: string;
+    readonly parentCreatedAt: string;
+}
+/**
+ * Projects one wire `Reply` row into a synthesized
+ * {@link HistoryEvent} of kind `update_replied`. The parent
+ * `Update.id` lands on `parent_update_id`; `Reply.kind` lands on
+ * `reply_kind` (separate from `activity_logs.event` taxonomy per
+ * the Decision 2 closure probe finding).
+ *
+ * `Reply.created_at` is nullable per the probe introspection;
+ * fallback chain: `Reply.created_at` → `Reply.updated_at` →
+ * the parent Update's projected timestamp. The final fallback
+ * is load-bearing: the event schema requires `created_at` to be
+ * non-empty (`min(1)`) and the parent's timestamp is guaranteed
+ * non-empty by `projectUpdateRow`'s `created_at ?? edited_at`
+ * resolution (Codex impl review round 1 P2-2). A Reply with both
+ * timestamps null then merges right next to its parent on the
+ * chronological stream.
+ */
+export declare const projectReplyRow: (inputs: ProjectReplyRowInputs) => HistoryEvent;
+/**
+ * Per-source pagination state surfaced on the
+ * {@link FetchItemHistoryResult} so the NDJSON trailer carries
+ * resumption hints. Two sources paginate independently; the
+ * trailer's `meta` carries both denominators so an agent
+ * resuming a walk knows which page to re-issue per source.
+ *
+ * - `activity_logs.last_page` — the last activity-log page the
+ *   walker drained. `null` when the walker exhausted the source
+ *   (no more pages); a number when stopped mid-walk
+ *   (`--limit` or wall-clock cap fired).
+ * - `updates.last_page` — same semantics for the updates source.
+ */
+export interface PerSourcePaginationState {
+    readonly activity_logs: {
+        readonly last_page: number | null;
+    };
+    readonly updates: {
+        readonly last_page: number | null;
+    };
+}
+/**
+ * Inputs to {@link fetchItemHistory}.
+ *
+ * - `client` — resolved {@link MondayClient} so the fetch inherits
+ *   `--retry` + `--verbose`-complexity injection (mirrors M22's
+ *   `fetchUsage` + M23's `fetchBoardFavorites` shape).
+ * - `itemId` — the target item. Branded {@link ItemId} (numeric-
+ *   string; parsed at the command argv boundary).
+ * - `boardId` — Monday's `activity_logs` resolver lives under
+ *   `boards(ids:)`, so the walker needs the item's parent board
+ *   ID. The command-action looks this up via `lookupItemBoard`
+ *   before constructing inputs.
+ * - `since` / `until` — wall-clock filters (ISO-8601). Both
+ *   optional; absent → unbounded on that side. Threaded through
+ *   to `activity_logs(from:, to:)`; the updates source filters
+ *   client-side against `Update.created_at` (Monday's `updates`
+ *   resolver doesn't expose a wall-clock filter as of API
+ *   `2026-01`).
+ * - `activityLogsPage` — 1-indexed page number for the
+ *   `activity_logs` source. Maps to Monday's `page:` arg.
+ * - `updatesPage` — 1-indexed page number for the `updates`
+ *   source. Independent of `activityLogsPage`.
+ * - `limit` — per-source per-call slice size (Monday's `limit:`
+ *   arg on both `activity_logs` and `updates`). Default
+ *   {@link DEFAULT_HISTORY_PAGE_SIZE}; hard cap
+ *   {@link HARD_CAP_HISTORY_PAGE_SIZE}.
+ * - `kinds` — optional projection filter; only events whose
+ *   `kind` is in the set are returned. Applied AFTER projection
+ *   (so unknown-event-kind warnings still surface for filtered
+ *   events; the filter narrows the returned `data` array, not
+ *   the merge denominator). The walker drains every page either
+ *   way; the filter is purely projection-side.
+ * - `onItem` — streaming hook per the `--stream` path. Called
+ *   per merged event per the ordered output (NOT per arrival —
+ *   merging requires the full slice resident; see
+ *   `mergeByCreatedAt` semantics).
+ */
+export interface FetchItemHistoryInputs {
+    readonly client: MondayClient;
+    readonly itemId: ItemId;
+    readonly boardId: string;
+    readonly since?: string;
+    readonly until?: string;
+    readonly activityLogsPage?: number;
+    readonly updatesPage?: number;
+    readonly limit?: number;
+    readonly kinds?: readonly HistoryEvent['kind'][];
+    readonly onItem?: (event: HistoryEvent) => void | Promise<void>;
+}
+/**
+ * Result of the two-source merged-history walker. Carries:
+ *
+ * - `events` — chronologically-merged event array (or the
+ *   `--kinds`-filtered subset).
+ * - `pagination` — per-source pagination state for NDJSON
+ *   trailer / agent-resumption.
+ * - `warnings` — `unknown_event_kind` warnings (one per unique
+ *   unrecognised event observed; see
+ *   {@link buildUnknownEventKindWarning}).
+ * - `complexity` — last-call `meta.complexity` (under
+ *   `--verbose` only); two-source merge picks the larger of
+ *   the per-source values (or `null` outside `--verbose`).
+ * - `source` — always `'live'` for v0.3. activity_logs + updates
+ *   are pure reads with no per-call cache; the action-layer
+ *   wrapping aggregates this with the item-board lookup's cache
+ *   state (which may be cache-hit) via `SourceAggregator` at M24
+ *   impl, mirroring the M23 cross-board-search source shape.
+ */
+export interface FetchItemHistoryResult {
+    readonly events: readonly HistoryEvent[];
+    readonly pagination: PerSourcePaginationState;
+    readonly warnings: readonly UnknownEventKindWarning[];
+    readonly complexity: Complexity | null;
+    readonly source: 'live';
+}
+/**
+ * Two-source merged-history walker. Issues two independent
+ * GraphQL calls (activity_logs + updates), filters + projects
+ * each per Decision 2 closure ratified shape, merges
+ * chronologically, aggregates `unknown_event_kind` warnings,
+ * applies optional `--kinds` projection filter, and streams via
+ * `inputs.onItem` (per-merged-event AFTER the merge — merging
+ * requires full slice resident per the `mergeByCreatedAt`
+ * docstring).
+ *
+ * **`source: 'live'` constant.** activity_logs + updates are
+ * pure reads with no per-call cache; the action layer aggregates
+ * this with the item-board lookup's `'live'` source via
+ * `SourceAggregator` and resolves the envelope's `meta.source`
+ * from the aggregator's resolved state (mirrors M23
+ * cross-board-search).
+ *
+ * **`complexity`** is the larger of the two stages' per-call
+ * complexity values (under `--verbose` only; null outside). Two
+ * independent calls → take the worst-case stage so agents see
+ * the more conservative budget snapshot rather than averaging.
+ *
+ * **Per-source pagination state.** Each source's `last_page` is
+ * the page number the walker DRAINED if the response returned a
+ * full slice (`response.length === limit` → more pages likely);
+ * `null` when the response returned less than `limit` rows
+ * (source exhausted). Monday's page-numbered surfaces have no
+ * "next" sentinel; the heuristic mirrors the v0.2 page-walker
+ * shape.
+ */
+export declare const fetchItemHistory: (inputs: FetchItemHistoryInputs) => Promise<FetchItemHistoryResult>;
+/**
+ * Adapter from a {@link FetchItemHistoryResult}'s `warnings`
+ * array to the envelope-shaped {@link Warning} array consumed by
+ * `emitSuccess`. Pre-flight pure helper — type-narrows the
+ * `code` discriminator so the envelope's `warnings[]` slot
+ * carries the precise shape rather than a generic `Warning`.
+ */
+export declare const toEnvelopeWarnings: (warnings: readonly UnknownEventKindWarning[]) => readonly Warning[];
+//# sourceMappingURL=item-history-projection.d.ts.map