@37signals/basecamp 0.18.0 → 0.19.0

package/dist/services/recordings-extensions.js

@@ -0,0 +1,1940 @@
+/**
+ * `RecordingsService.summarize` — a compact projection of one recording,
+ * resolved from the pointer an account event feed row or a webhook carries
+ * (bucket id, recording id, and the event type or recording type) through the
+ * typed read that type names.
+ *
+ * It exists for consumers that must decide something about a recording without
+ * paying for its full payload: an agent connector's admission step, an MCP tool
+ * answering "what is this?".
+ *
+ * The SDK has no untyped recording read (BC3 has no such route), so the type is
+ * the routing key: `comment.created` reads a comment, `card.created` reads a
+ * card, and so on — one typed read per type. Chat lines are the exception,
+ * because their read needs the Campfire id and the pointer does not carry it;
+ * `summarize` discovers the Campfire first (see {@link RecordingsService.summarize}
+ * and the discovery notes further down).
+ *
+ * This is hand-written composition over the generated services (SPEC §18,
+ * Appendix F). It makes no wire request of its own, and it mints no operation
+ * identity: hooks see the constituent reads under their own names (§18 rule 3).
+ * It lives in `src/services/*-extensions.ts` and is wired in `client.ts`, the
+ * placement §18 rule 5 designates for TypeScript.
+ */
+import { BasecampError, Errors, isBasecampError, truncateErrorMessage } from "../errors.js";
+import { RecordingsService as GeneratedRecordingsService } from "../generated/services/recordings.js";
+import { readMentions } from "./mentions.js";
+/**
+ * The two mention fields of a summary, from one walk of the rich text.
+ *
+ * `unnameable_mention_ids` is omitted rather than set to `[]` when there is
+ * nothing to report, so the key appears only on the payloads where
+ * `mentioned_person_ids` is actually short. `mentioned_person_ids` is always
+ * present, which is the existing contract.
+ */
+function mentionsOf(richText) {
+    const { ids, unnameable } = readMentions(richText);
+    return unnameable.length > 0
+        ? { mentioned_person_ids: ids, unnameable_mention_ids: unnameable }
+        : { mentioned_person_ids: ids };
+}
+/**
+ * The base class for every failure that is the composite's own conclusion
+ * rather than one read's HTTP answer.
+ *
+ * It is a {@link BasecampError} so an existing `catch` keeps working, and it
+ * carries a `kind` so the conclusions stay distinguishable from each other and
+ * from the read errors whose `code` they share. Every one of them is
+ * **statusless**: no single request returned a status that describes the
+ * conclusion, so a consumer seeing `code: "not_found"` with no `httpStatus`
+ * knows it is looking at a composite's verdict and not at a 404 off the wire.
+ */
+export class RecordingSummaryError extends BasecampError {
+    kind;
+    constructor(kind, code, message, options) {
+        super(code, message, { ...options, retryable: false });
+        this.name = "RecordingSummaryError";
+        this.kind = kind;
+    }
+}
+/**
+ * A {@link RecordingRef} `summarize` cannot route, raised before any request.
+ *
+ * `usage`: nothing was asked of the API — the pointer names no read.
+ */
+export class RecordingRoutingError extends RecordingSummaryError {
+    ref;
+    constructor(ref, kind) {
+        // Raw, and the fallback is on exactly "", as Go's RecordingRoutingError
+        // reads them: routing trims before matching, but the message reports what
+        // the caller actually passed.
+        const key = ref.recordingType !== undefined && ref.recordingType !== ""
+            ? ref.recordingType
+            : (ref.eventType ?? "");
+        const reason = kind === "no_recording_type"
+            ? "event type names no recording type"
+            : "no typed read for recording type";
+        super(kind, "usage", `${reason}: ${JSON.stringify(key)}`, {
+            hint: kind === "no_recording_type"
+                ? "resolve the recording from your own record of what the event referred to"
+                : "pass a recording type summarizableRecordingTypes() lists, or an event type summarizableEventTypes() lists",
+        });
+        this.name = "RecordingRoutingError";
+        this.ref = ref;
+    }
+}
+/** A chat line found under no visible Campfire. */
+export class UnresolvedRecordingError extends RecordingSummaryError {
+    bucketId;
+    recordingId;
+    /** The candidates tried, in order; empty when the bucket has no visible Campfire at all. */
+    campfireIds;
+    /**
+     * Whether the cached discovery sources were re-read before concluding. False
+     * when every source had been read within the last
+     * {@link CAMPFIRE_INDEX_MIN_REFRESH_MS}, so a Campfire created in that window
+     * was not seen: the conclusion stands on data up to that old, and a retry
+     * after the floor sees the current sources.
+     */
+    refreshed;
+    /**
+     * Candidates from the cache that the refreshed sources no longer list —
+     * Campfires the caller could see when the cache filled and cannot now. Set
+     * only when {@link refreshed}.
+     */
+    staleCampfireIds;
+    constructor(init) {
+        super("recording_unresolved", "not_found", `chat line found under no visible campfire: line ${init.recordingId} in bucket ${init.bucketId} ` +
+            `(tried ${init.campfireIds.length} campfires)`, {
+            hint: "the line is under no Campfire this credential can currently see; retry once visibility may have changed",
+        });
+        this.name = "UnresolvedRecordingError";
+        this.bucketId = init.bucketId;
+        this.recordingId = init.recordingId;
+        this.campfireIds = init.campfireIds;
+        this.refreshed = init.refreshed;
+        this.staleCampfireIds = init.staleCampfireIds;
+    }
+}
+/**
+ * Discovery stopped short of a conclusion, and why.
+ *
+ * `usage`, non-retryable, settled across every port on
+ * {@link https://app.basecamp.com/2914079/buckets/48699913/card_tables/cards/10308122086 | card 40}
+ * after the merged ports shipped two different answers — this one and Python
+ * said `api_error`, Kotlin said `usage`, and a caller got exit 7 from one SDK
+ * and exit 1 from another for the same condition.
+ *
+ * `usage` is one of only THREE coarse codes no HTTP response can produce: the
+ * status mapping yields `auth_required`, `forbidden`, `not_found`,
+ * `rate_limit`, `validation`, `limit_exceeded` and `api_error`, and `network`
+ * and `ambiguous` are equally unreachable from a status. `usage` is the one of
+ * those three that also describes a call the SDK declined to complete, which is
+ * why it and not the other two. A verdict the composite reached on its own
+ * therefore can never be read back as a constituent read's own answer — the
+ * property the composite exists to protect. It is
+ * explicitly not `not_found`, because nothing left unsearched may be reported
+ * absent.
+ *
+ * Retryability is a separate field and is unchanged: {@link
+ * RecordingSummaryError} forces `retryable: false` on every identity, and both
+ * of this one's reasons are deterministic for the same account state, so a
+ * retry loop would re-run the identical search forever.
+ */
+export class CampfireDiscoveryIncompleteError extends RecordingSummaryError {
+    bucketId;
+    recordingId;
+    reason;
+    constructor(init) {
+        super("campfire_discovery_incomplete", "usage", `campfire discovery incomplete: line ${init.recordingId} in bucket ${init.bucketId}: ${init.reason}`, { hint: "candidates were left unsearched, so the line cannot be reported absent" });
+        this.name = "CampfireDiscoveryIncompleteError";
+        this.bucketId = init.bucketId;
+        this.recordingId = init.recordingId;
+        this.reason = init.reason;
+    }
+}
+/**
+ * A read whose bucket disagrees with the pointer.
+ *
+ * `usage`: the pointer named a bucket the recording is not in, which is the
+ * caller's argument being wrong rather than the API misbehaving. This doc
+ * comment argued the opposite — `api_error`, citing SPEC §6's statusless rule —
+ * for as long as the code said so, and went on saying it after the code
+ * changed, which is the half of a rename that editor hover and generated API
+ * docs actually show a consumer.
+ *
+ * The ports on `main` did NOT agree here, and the disagreement was bigger than
+ * the value: `exitCode` derives from the code, so this identity exited 1 in
+ * Python, Ruby, Kotlin and this port (`usage`) and 2 in Rust (`not_found`, "the
+ * recording the pointer names is not where it was looked for"). Settled for
+ * every SDK on {@link https://app.basecamp.com/2914079/buckets/48699913/card_tables/cards/10308966794 | card 41} as `usage`, and on the
+ * argument rather than the four-to-one majority: `not_found` says the recording
+ * is not there, which is false — the read FOUND it, in another bucket, and
+ * returned it. Nothing is absent. What failed is the caller's pointer.
+ *
+ * The shared fixture had no case for this identity at all, so nothing pinned
+ * the code: five ports carried two answers and two carried none, with every
+ * case green in all seven. It has one now, and it pins the code alongside the
+ * identity.
+ */
+export class BucketMismatchError extends RecordingSummaryError {
+    ref;
+    /** The bucket the read returned. */
+    bucketId;
+    constructor(ref, bucketId) {
+        super("bucket_mismatch", 
+        // Settled for every SDK on card 41; see the class doc above for the
+        // argument. The fixture had no case for this identity, so nothing pinned
+        // the code and five ports carried two answers with every case green. It
+        // has one now, so a port that reaches a different answer fails a case.
+        "usage", `recording is not in the requested bucket: recording ${ref.recordingId} is in bucket ${bucketId}, not ${ref.bucketId}`);
+        this.name = "BucketMismatchError";
+        this.ref = ref;
+        this.bucketId = bucketId;
+    }
+}
+/**
+ * Maps the subject of an account event feed type — everything before its final
+ * `.` — to a read. This is the feed's catalog (bc3 `Event::EventType`) minus
+ * `boost`, which names no recording type and is refused explicitly rather than
+ * left to fall through as unknown.
+ */
+const EVENT_SUBJECTS = new Map([
+    ["comment", "comment"],
+    ["message", "message"],
+    ["todo", "todo"],
+    ["card", "card"],
+    ["chat.line", "chatLine"],
+]);
+/**
+ * Maps BC3's recording type strings to a read. It is the routing contract, and
+ * it is a DELIBERATE set, not an exhaustive one: the recording types the
+ * account event feed's trigger matrix names (comment, message, to-do, card,
+ * chat line), plus the content and tool recordings a consumer reasoning about
+ * those is likely to hold an id for. Chat lines are matched by prefix
+ * (`Chat::Lines::Text`, `::RichText`, `::Code`, `::Upload`, `::Integration` all
+ * read through the same route); everything else exactly.
+ *
+ * A type outside this set is `unknown_recording_type` by design, whether or not
+ * the SDK has an id-only read for it — `Timesheet::Entry` and `Gauge::Needle`
+ * do, and are not routed; `Client::Reply` and `Forward::Reply` cannot be, since
+ * their reads need a parent id the pointer does not carry. Widening the set is
+ * a product decision, not a gap: add the type here, its projection in
+ * `readSummary`, and a case in `conformance/tests/recording_summary.json`, the
+ * fixture every port implements.
+ *
+ * A `Map`, not an object literal: the key is an untrusted string off an event
+ * feed row or a webhook, and `{}["constructor"]` is a hit. A routing table that
+ * answers for every `Object.prototype` member would route those to something
+ * that is not a read at all.
+ */
+const RECORDING_TYPES = new Map([
+    ["Comment", "comment"],
+    ["Message", "message"],
+    ["Todo", "todo"],
+    ["Kanban::Card", "card"],
+    ["Document", "document"],
+    ["Upload", "upload"],
+    ["Schedule::Entry", "scheduleEntry"],
+    ["Question", "question"],
+    ["Question::Answer", "questionAnswer"],
+    ["Todolist", "todolist"],
+    ["Vault", "vault"],
+    ["Inbox::Forward", "forward"],
+    ["Client::Approval", "clientApproval"],
+    ["Client::Correspondence", "clientCorrespondence"],
+    ["GoogleDocument", "googleDocument"],
+    ["CloudFile", "cloudFile"],
+    ["Kanban::Step", "cardStep"],
+    ["Questionnaire", "questionnaire"],
+    ["Schedule", "schedule"],
+    ["Todoset", "todoset"],
+    ["Message::Board", "messageBoard"],
+    ["Kanban::Board", "cardTable"],
+    ["Kanban::Column", "cardColumn"],
+    ["Inbox", "inbox"],
+    ["Chat::Transcript", "campfire"],
+]);
+const CHAT_LINE_TYPE_PREFIX = "Chat::Lines::";
+/**
+ * The recording types `summarize` routes by `recordingType`, sorted, with the
+ * `Chat::Lines` subtypes represented by their shared prefix
+ * (`"Chat::Lines::*"`). The set is deliberate rather than exhaustive — see
+ * {@link RECORDING_TYPES} — and any other type is `unknown_recording_type` by
+ * design.
+ */
+export function summarizableRecordingTypes() {
+    return [...RECORDING_TYPES.keys(), `${CHAT_LINE_TYPE_PREFIX}*`].sort();
+}
+/**
+ * The account event feed subjects `summarize` routes by `eventType` — an event
+ * type is `<subject>.<action>`, and any action on a listed subject routes to
+ * that subject's read — sorted. `boost` is absent on purpose: it is
+ * `no_recording_type`.
+ */
+export function summarizableEventTypes() {
+    return [...EVENT_SUBJECTS.keys()].map((subject) => `${subject}.*`).sort();
+}
+/**
+ * Whether a chat line subtype carries rich text — the two that declare
+ * `rich_text_attribute :content` in BC3, and so the only two whose content can
+ * hold a mention. A Text line's content is HTML-escaped on the way out
+ * (`content_helper.rb`, `format_chat_line_with`), a Code line's is served
+ * verbatim — a snippet that happens to contain a `bc-attachment` tag — and an
+ * Upload line has no content.
+ */
+function chatLineIsRichText(lineType) {
+    return lineType === "Chat::Lines::RichText" || lineType === "Chat::Lines::Integration";
+}
+/** Picks the read for a ref. `recordingType` wins when set. */
+function routeRecording(ref) {
+    const recordingType = ref.recordingType?.trim() ?? "";
+    if (recordingType !== "") {
+        if (recordingType.startsWith(CHAT_LINE_TYPE_PREFIX))
+            return "chatLine";
+        const kind = RECORDING_TYPES.get(recordingType);
+        if (kind !== undefined)
+            return kind;
+        throw new RecordingRoutingError(ref, "unknown_recording_type");
+    }
+    const eventType = ref.eventType?.trim() ?? "";
+    if (eventType === "")
+        throw new RecordingRoutingError(ref, "unknown_recording_type");
+    // A feed type is "<subject>.<action>"; the subject names the recording type.
+    // A string with no action is not a feed type and is not routed.
+    const dot = eventType.lastIndexOf(".");
+    if (dot <= 0 || dot === eventType.length - 1) {
+        throw new RecordingRoutingError(ref, "unknown_recording_type");
+    }
+    const subject = eventType.slice(0, dot);
+    if (subject === "boost")
+        throw new RecordingRoutingError(ref, "no_recording_type");
+    const kind = EVENT_SUBJECTS.get(subject);
+    if (kind !== undefined)
+        return kind;
+    throw new RecordingRoutingError(ref, "unknown_recording_type");
+}
+// =============================================================================
+// Campfire discovery
+// =============================================================================
+/**
+ * How long a cached discovery source — a bucket's project dock, the account's
+ * Campfire listing — is reused before it is read again.
+ */
+export const CAMPFIRE_INDEX_TTL_MS = 10 * 60 * 1000;
+/**
+ * Bounds the refresh-on-miss: a line found under no candidate re-reads the
+ * cached sources, but not more often than this per source, so a run of
+ * unresolvable lines cannot turn into a listing per line.
+ * {@link UnresolvedRecordingError.refreshed} says whether the floor applied.
+ */
+const CAMPFIRE_INDEX_MIN_REFRESH_MS = 30 * 1000;
+/**
+ * Bounds how many Campfires one `summarize` call tries, across both sources and
+ * the refresh. A project has one Campfire and a handful of pings; a bucket past
+ * this bound is not a shape BC3 produces, and the call reports
+ * `campfire_discovery_incomplete` rather than calling the rest absent.
+ */
+export const MAX_CAMPFIRE_CANDIDATES = 50;
+/**
+ * Caps the account-wide Campfire listing the fallback source reads. A listing
+ * that overflows it is not cached and the call reports
+ * `campfire_discovery_incomplete`: the dock covers every project, so the
+ * listing only ever serves the leftover, and an account with more Campfires
+ * than this should not pay a full walk per ten minutes for it.
+ */
+export const MAX_CAMPFIRE_LISTING = 1000;
+/**
+ * Bounds each discovery cache's entry count. The dock cache holds one snapshot
+ * per bucket consulted within the TTL: a connector listening across every
+ * project an agent can see touches hundreds of buckets, not thousands, and a
+ * snapshot is a handful of ids, so 1024 is generous headroom, and the bound
+ * exists so that a process alive for weeks can never grow past it whatever it
+ * sees. When the bound is reached the oldest-fetched entries go first,
+ * deterministically.
+ */
+const CAMPFIRE_INDEX_MAX_ITEMS = 1024;
+/**
+ * A per-key cache with single-flight loading: concurrent callers for one key
+ * await the one load in progress rather than loading again, and a failed load
+ * leaves the previous value in place and is not cached.
+ *
+ * The clock is `performance.now()`, which is monotonic: a wall-clock adjustment
+ * cannot make a snapshot look newer than it is, or make the refresh floor
+ * elapse early.
+ *
+ * Go's version additionally distinguishes a load that failed because the
+ * *loading caller's* context was cancelled, so a live waiter can load for
+ * itself. There is no per-call cancellation to attribute here — the services
+ * take no signal — so a failed load's rejection is simply shared by everyone
+ * waiting on it, which is the half of that rule that matters: N waiters never
+ * re-run one failed load N times.
+ */
+class TtlCache {
+    #entries = new Map();
+    #inflight = new Map();
+    #ttlMs;
+    #floorMs;
+    #maxItems;
+    #now;
+    #seq = 0;
+    constructor(ttlMs, floorMs, maxItems, now = () => performance.now()) {
+        this.#ttlMs = ttlMs;
+        this.#floorMs = floorMs;
+        this.#maxItems = maxItems;
+        this.#now = now;
+    }
+    /**
+     * The cached value for `key` when one is within the TTL, without loading. It
+     * lets a caller consult what a source already holds before deciding whether
+     * to pay for a fetch of it.
+     */
+    peek(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined || this.#now() - entry.fetchedAt >= this.#ttlMs)
+            return undefined;
+        return { value: entry.value, fetchedAt: entry.fetchedAt, cached: true };
+    }
+    /**
+     * The value for `key`, loading it when absent or older than the TTL — or,
+     * with `refresh` set, older than the floor.
+     */
+    async get(key, refresh, load) {
+        const entry = this.#entries.get(key);
+        if (entry !== undefined) {
+            const age = this.#now() - entry.fetchedAt;
+            if (age < this.#ttlMs && (!refresh || age < this.#floorMs)) {
+                return { value: entry.value, fetchedAt: entry.fetchedAt, cached: true };
+            }
+        }
+        const pending = this.#inflight.get(key);
+        // The load this call waits on is this call's load: its value is handed over
+        // as fresh, not as something that predated the call.
+        //
+        // A waiter shares the load's outcome unconditionally, success or failure,
+        // and nothing here reads the rejection to decide otherwise. That is what
+        // keeps one failed load from becoming one request per waiter, and it is
+        // also why the trap Go's `callerDone` exists to avoid cannot be sprung
+        // here: Go has to tell a load that failed on the LOADING caller's dead
+        // context from one that failed on its own, so a still-live waiter can load
+        // again, and it deliberately refuses to decide that from the error alone —
+        // an `http.Client.Timeout` satisfies `errors.Is(err,
+        // context.DeadlineExceeded)` with the owner still live. TypeScript has the
+        // same ambiguity in a sharper form, since an aborted `fetch` rejects with
+        // an `AbortError` whether a timeout or a caller fired the signal. There is
+        // nothing to attribute: the services take no per-call signal, so no caller
+        // can be dead while another is live, and no waiter ever re-runs a load.
+        //
+        // That is a property of the CALL SITES, not of the client — client.ts does
+        // thread an AbortSignal through its middleware and retry loop. Giving
+        // summarize() a per-call signal would make a load abortable by one caller
+        // while another still waits, and this paragraph would stop being true: Go's
+        // attribution would have to be ported with it, and it cannot be done from
+        // the rejection, since an aborted fetch rejects with an AbortError
+        // whichever signal fired.
+        if (pending !== undefined)
+            return pending;
+        // The order of these three statements is the release guarantee, and it is
+        // load-bearing. An `async` function never throws synchronously — a throw in
+        // its body becomes a rejection — so invoking the wrapper always yields a
+        // promise; `.finally` is attached to that promise; and only then is the key
+        // marked in flight. There is therefore no instant at which the slot is held
+        // without a release handler attached to the thing holding it, and every way
+        // the wrapper can end — `load()` throwing synchronously, its promise
+        // rejecting, `#publish` throwing — settles that promise and runs the
+        // `finally`. Go reaches the same guarantee the other way round, with a
+        // deferred publish that survives a panicking loader.
+        //
+        // The one exit this cannot cover is a `load()` that never settles, which
+        // would hold the slot and park every later caller for the life of the
+        // process. Go's waiters escape that through their own context; these have
+        // no signal to escape with. What closes it is one layer down: every request
+        // a loader makes carries the client's request timeout, so a load that is
+        // going nowhere rejects rather than hanging.
+        //
+        // A loader must not re-enter this cache for its own key. It would not join
+        // the load in progress — the slot is taken after `load()` is invoked, where
+        // Go takes it before — and would start a second one. Neither loader here
+        // does; both call a single generated read.
+        const started = (async () => {
+            const value = await load();
+            return this.#publish(key, value);
+        })().finally(() => {
+            // A failed load leaves the previous entry in place and caches nothing; the
+            // key is released either way so the next caller can load again.
+            //
+            // By IDENTITY, not by key. A blind `delete(key)` would drop whatever is
+            // registered there, and if that were ever a later caller's live load, the
+            // single-flight guarantee would go with it — two concurrent account-wide
+            // listings under one key, which is process-wide, since that key is a
+            // constant. The ordering above makes that unreachable today: a later
+            // caller can only register after this handler has vacated the slot,
+            // because until then it sees the pending promise and waits on it. The
+            // guard makes the property local anyway, so a second vacate path added
+            // later cannot quietly reintroduce it.
+            if (this.#inflight.get(key) === started)
+                this.#inflight.delete(key);
+        });
+        this.#inflight.set(key, started);
+        return started;
+    }
+    #publish(key, value) {
+        const fetchedAt = this.#now();
+        this.#sweep();
+        this.#makeRoom(key);
+        this.#entries.set(key, { value, fetchedAt, seq: ++this.#seq });
+        return { value, fetchedAt, cached: false };
+    }
+    /**
+     * Drops every entry past its TTL. It runs at each publication — the one
+     * moment the cache does work proportional to a miss anyway — so a long-lived
+     * client that has seen many buckets keeps a snapshot for at most a TTL past
+     * its last use plus the interval to the next load on any key, rather than for
+     * its lifetime.
+     */
+    #sweep() {
+        const now = this.#now();
+        for (const [key, entry] of this.#entries) {
+            if (now - entry.fetchedAt >= this.#ttlMs)
+                this.#entries.delete(key);
+        }
+    }
+    /**
+     * Evicts the oldest-fetched entries until the one about to be stored for
+     * `key` fits under the bound — oldest by fetch time, and by publication order
+     * among equals, so the choice is total rather than whatever iteration order
+     * happens to visit first. Oldest-first is also the right order: the entry
+     * nearest its TTL is the one least worth keeping.
+     */
+    #makeRoom(key) {
+        if (this.#maxItems <= 0)
+            return;
+        if (this.#entries.has(key))
+            return; // an overwrite takes no new room
+        while (this.#entries.size >= this.#maxItems) {
+            let oldestKey;
+            let oldest = Number.POSITIVE_INFINITY;
+            let oldestSeq = Number.POSITIVE_INFINITY;
+            for (const [candidate, entry] of this.#entries) {
+                if (entry.fetchedAt < oldest || (entry.fetchedAt === oldest && entry.seq < oldestSeq)) {
+                    oldestKey = candidate;
+                    oldest = entry.fetchedAt;
+                    oldestSeq = entry.seq;
+                }
+            }
+            if (oldestKey === undefined)
+                return;
+            this.#entries.delete(oldestKey);
+        }
+    }
+}
+/** The single key the account-wide listing cache is stored under. */
+const LISTING_KEY = "campfires";
+/**
+ * The two discovery sources.
+ *
+ * A client is bound to one credential and one account, so entries are never
+ * shared across authorization contexts and a bucket id is a sufficient key.
+ * Expired snapshots are swept at each load and each cache is bounded
+ * ({@link CAMPFIRE_INDEX_MAX_ITEMS}, oldest out first), so the index holds at
+ * most the buckets consulted within the last TTL, and never more than the
+ * bound, whatever the client has seen.
+ */
+class CampfireIndex {
+    #docks;
+    #listings;
+    constructor(now) {
+        this.#docks = new TtlCache(CAMPFIRE_INDEX_TTL_MS, CAMPFIRE_INDEX_MIN_REFRESH_MS, CAMPFIRE_INDEX_MAX_ITEMS, now);
+        this.#listings = new TtlCache(CAMPFIRE_INDEX_TTL_MS, CAMPFIRE_INDEX_MIN_REFRESH_MS, CAMPFIRE_INDEX_MAX_ITEMS, now);
+    }
+    /**
+     * The Campfire ids a bucket's project dock names. A bucket that is not a
+     * project (a 404 on the project read) has none; any other failure of the read
+     * is raised.
+     */
+    async dockCampfires(sources, bucketId, refresh) {
+        const hit = await this.#docks.get(bucketId, refresh, async () => {
+            let project;
+            try {
+                project = await sources.projects.get(bucketId);
+            }
+            catch (err) {
+                if (isNotFound(err))
+                    return [];
+                throw err;
+            }
+            // Two layers, as Go has two: its decoder refuses a dock id that is not a
+            // number and fails the whole project read, and only then does it skip a
+            // zero id. TypeScript decodes nothing, so the first layer is the explicit
+            // refusal below — without it a malformed id would be dropped silently and
+            // discovery could go on to report the line unresolved, a composite
+            // verdict standing in for a failed read.
+            return sourceItems(sourceObject(project, "the project read").dock, "the project dock")
+                .filter((item) => recordingText(item.name, "a project dock item name", DISCOVERY_HINT) === "chat")
+                .map((item) => numericId(item.id, "project dock item"))
+                .filter((id) => id !== 0);
+        });
+        return { ids: hit.value, fetchedAt: hit.fetchedAt, cached: hit.cached };
+    }
+    /**
+     * The Campfire ids the cached account-wide listing shows in a bucket, without
+     * fetching: `undefined` when the listing is not cached or has expired.
+     */
+    cachedListedCampfires(bucketId) {
+        const hit = this.#listings.peek(LISTING_KEY);
+        if (hit === undefined)
+            return undefined;
+        return { ids: [...(hit.value.get(bucketId) ?? [])], fetchedAt: hit.fetchedAt, cached: true };
+    }
+    /**
+     * The Campfire ids the account-wide listing shows in a bucket. A listing that
+     * overflows {@link MAX_CAMPFIRE_LISTING} is not cached and is reported as
+     * incomplete discovery by the caller.
+     */
+    async listedCampfires(sources, bucketId, refresh) {
+        const hit = await this.#listings.get(LISTING_KEY, refresh, async () => {
+            const list = await sources.campfires.list({ maxItems: MAX_CAMPFIRE_LISTING });
+            if (list.meta.truncated)
+                throw new CampfireListingOverflow();
+            const byBucket = new Map();
+            for (const campfire of sourceItems(list, "the campfire listing")) {
+                // The bucket OBJECT, not only its id: a string or an array here left
+                // `?.id` undefined and the entry was dropped in silence, where Go's
+                // decode of the same body fails the listing read. A JSON null is the
+                // measured exception — the zero struct, whose zero bucket id the filter
+                // below skips, exactly as Go's `c.Bucket == nil` does.
+                const bucket = sourceObject(campfire.bucket, "campfire listing bucket");
+                // Go filters this source on the bucket alone — a zero campfire id is a
+                // candidate there, spends budget, and lands in the unresolved verdict's
+                // campfireIds — so it is kept here too. Only a value Go's decoder would
+                // have refused outright is refused.
+                const campfireId = numericId(campfire.id, "campfire listing entry");
+                // `wireInteger`, not `numericId`: Go's line here is `c.Bucket == nil ||
+                // c.Bucket.ID == 0` and then `byBucket[c.Bucket.ID]` — a map key and a
+                // comparand. Only `c.ID` below is ever put in a URL, so only it carries
+                // the safe-integer clause. Routing this one through `numericId` failed
+                // the whole listing over one entry in ANOTHER bucket, which is worse
+                // than what happens now: such an entry is skipped, and the healthy ones
+                // beside it are kept.
+                const listedBucketId = wireInteger(bucket.id, "campfire listing bucket");
+                if (listedBucketId === 0)
+                    continue;
+                // Unreachable while `summarize` refuses a caller `bucketId` past 2^53:
+                // every rounded value above that is itself above MAX_SAFE_INTEGER, so
+                // it can never equal a safe id and the filter below already drops it.
+                // Stated here anyway, because the property it rests on lives in another
+                // method — and reverting this line is behaviour-neutral, which the
+                // guard-checking harness records as such rather than as a gap. What
+                // makes it worth stating: rounding is not injective, so two int64
+                // buckets can land on one double, and a key built from one would offer
+                // another project's Campfire as a candidate.
+                if (!Number.isSafeInteger(listedBucketId))
+                    continue;
+                const ids = byBucket.get(listedBucketId);
+                if (ids === undefined)
+                    byBucket.set(listedBucketId, [campfireId]);
+                else
+                    ids.push(campfireId);
+            }
+            return byBucket;
+        });
+        return { ids: [...(hit.value.get(bucketId) ?? [])], fetchedAt: hit.fetchedAt, cached: hit.cached };
+    }
+}
+/**
+ * The load failure for a listing past its cap; `#resolveChatLine` turns it into
+ * the typed {@link CampfireDiscoveryIncompleteError}. Module-private and never
+ * a `BasecampError`, so it can never be mistaken for a read error a caller
+ * could see or reach one uncaught.
+ */
+class CampfireListingOverflow extends Error {
+    constructor() {
+        // Go's sentinel carries the constant's NAME, not its value, and `reason`
+        // is a public field a consumer or a shared fixture can match on.
+        super("campfire listing exceeds MaxCampfireListing");
+        this.name = "CampfireListingOverflow";
+    }
+}
+/**
+ * The body of a routed read, refused when it is not a recording object.
+ *
+ * Go decodes each read into a struct, so a body that is not a JSON object never
+ * reaches the projection: it fails the read. TypeScript decodes nothing, and
+ * the cost is not a cosmetic one — the arms dereference the body immediately
+ * (`c.title`), so a bare `"hello"` projected every scalar to its default and,
+ * worse, left `bucket` absent, which is how a recording in ANOTHER project came
+ * back as a match instead of a `bucket_mismatch`. A malformed body decided a
+ * verdict, which is the line at which this port replicates Go's decoder.
+ *
+ * `null` is the exception, and it is measured rather than assumed: `json.Unmarshal`
+ * takes a JSON null into a struct as a no-op, so Go returns the ZERO recording
+ * and no error. That is projected here as the zero recording too — and it is
+ * also the shape that used to throw a raw TypeError out of the SDK, since the
+ * arm dereferenced it before anything could check. An array is a decode error
+ * there, so it is refused here.
+ */
+function recordingBody(value) {
+    if (value === null)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw Errors.apiError(truncateErrorMessage(`the recording read returned ${describeWireValue(value)} rather than a recording`), undefined, {
+            retryable: false,
+            hint: "the response is malformed; the recording it names cannot be summarized from it",
+        });
+    }
+    return value;
+}
+/**
+ * A nested object a discovery source carries, refused when it is not one.
+ *
+ * The id sweep covered the id FIELD at each site and not the container around
+ * it, and the container has the same two failure modes with worse consequences.
+ * Measured through the generated structs: a dock or a listing entry that is not
+ * an object fails Go's decode outright, and a JSON `null` is the zero struct —
+ * whose empty name and zero ids each site already skips. TypeScript did neither:
+ * a non-object was read for fields it does not have and dropped in silence, and
+ * a `null` threw a raw TypeError out of the SDK on a body Go reads happily.
+ */
+function sourceObject(value, what, hint = DISCOVERY_HINT) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} is ${describeWireValue(value)} rather than an object`), undefined, { retryable: false, hint });
+    }
+    return value;
+}
+/**
+ * The hints these helpers carry. Two, because the same shape checks run on two
+ * different reads: a Campfire discovery source, and the recording itself.
+ *
+ * The projection borrowed the discovery wording for a while, so a malformed
+ * `assignees` on a to-do read advised the caller about Campfires. Fixing that in
+ * the container helpers left it unfixed one helper along, in `wireInteger` and
+ * `numericId`, whose recording-side callers went on saying it — which is why
+ * this is a parameter on every one of them rather than a constant inside the
+ * two that were noticed first.
+ */
+const DISCOVERY_HINT = "the discovery source's response is malformed; no Campfire can be read from it";
+const RECORDING_HINT = "the response is malformed; the recording cannot be summarized from it";
+/** {@link sourceItems}, for a list read off the recording rather than a source. */
+function wireItems(value, what) {
+    return sourceItems(value, what, RECORDING_HINT);
+}
+/** The same, for a list of them: absent is empty, a non-array is a failed read. */
+function sourceItems(value, what, hint = DISCOVERY_HINT) {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} is ${describeWireValue(value)} rather than a list`), undefined, { retryable: false, hint });
+    }
+    return value.map((item) => sourceObject(item, `${what} entry`, hint));
+}
+/**
+ * The whole number a wire field carries, or a failed read — the TYPE half only.
+ *
+ * Shared because Go's decoders agree on it everywhere: absent and JSON null are
+ * the zero value, and anything that is not a whole number in an int64 fails the
+ * read. What is NOT shared is what each site then does with the number, and a
+ * helper that decided that too would be the tidy kind of wrong: a rule reading
+ * like the reference's while applying one site's policy at another's. Each
+ * caller spells its own value rule beside the Go line it mirrors.
+ */
+const INT64_LIMIT = 2 ** 63;
+function wireInteger(value, what, hint = DISCOVERY_HINT) {
+    if (value === undefined || value === null)
+        return 0;
+    // The window is Go's int64, measured at both ends: 9223372036854775807 and
+    // -9223372036854775808 decode, and one past either is a decode error. An
+    // "any whole number" rule was wider than the reference at the top end, so a
+    // bucket id of 1e20 — a body Go refuses — came back as a bucket_mismatch
+    // naming a bucket that cannot exist.
+    //
+    // MEASURED IN GO, NOT IN THIS RUNTIME, and the two differ at exactly one
+    // point: `JSON.parse("9223372036854775807")` is 2^63 here, so the top of the
+    // window does NOT survive the parse and this guard refuses it. The negative
+    // end does survive. That over-refusal is reachable at one literal value, in
+    // the refusing direction, and it is declared in the TypeScript row of
+    // Appendix F rather than left for a reader to discover from this sentence
+    // asserting the opposite.
+    if (typeof value !== "number" || !Number.isInteger(value) || value >= INT64_LIMIT || value < -INT64_LIMIT) {
+        throw Errors.apiError(truncateErrorMessage(`${what} has an id that is not a usable whole number (${describeIdValue(value)})`), undefined, { retryable: false, hint });
+    }
+    return value;
+}
+/**
+ * The id a discovery source carried, read the way Go's decoder reads it.
+ *
+ * Three outcomes, and the first version of this had two of them wrong.
+ * `json.Unmarshal` into an `int64` treats an ABSENT key and a JSON `null` as
+ * the zero value and succeeds — Go then skips a zero id at its own filter — so
+ * neither is an error here either. A string, a fraction, or a number past
+ * int64 fails Go's decode outright and takes the whole read with it, which is
+ * the malformed-response shape SPEC §6 spells for a composite that cannot
+ * proceed with a 2xx body: `api_error`, statusless, non-retryable.
+ *
+ * Getting the first two wrong turned "skip this dock entry" into a failure of
+ * the entire summarize; getting the last wrong let a fractional id through to
+ * a request for `/chats/1.5/lines/{id}`.
+ *
+ * TWO GAPS, both stated rather than papered over. Go refuses the LITERAL — its
+ * decoder runs `strconv.ParseInt` over the raw token — so `1.0`, `1e2` and
+ * `7.7e1` are decode errors there. By the time this runs, `JSON.parse` has
+ * turned every one of those into the number 77, and the literal is gone: an
+ * exponent or trailing-zero spelling of a whole number is accepted here and
+ * refused there — `1.0` arrives as 1, `1e2` as 100, `7.7e1` as 77 — and this
+ * layer, which receives an already-parsed value, cannot tell any of them from
+ * the literal Go refuses. Not an impossibility, a placement: on the supported
+ * Node floor a `JSON.parse` reviver can read `context.source` and see the
+ * spelling (SPEC §19 says so for the large-integer case), so a decoder that
+ * wanted these distinctions could have them. This composite does not reach for
+ * one, because it would mean parsing every response body twice to refuse a
+ * spelling no BC3 endpoint emits. And
+ * the upper bound is 2^53, not int64, which is the same limit SPEC §19 waives for this SDK: an id
+ * past it cannot be held without rounding it into a different id, so refusing
+ * it is the honest answer even though Go decodes it.
+ *
+ * The int64 window's own two ends are not symmetric after rounding, and the
+ * message says so rather than pretending otherwise: 9223372036854775808 rounds
+ * to exactly 2^63 and is refused, while -9223372036854775809 — a decode error
+ * in Go — rounds to exactly -2^63, a legal value, and nothing at this layer can
+ * tell the two apart. One end is measurable after JSON.parse and the other is
+ * not.
+ */
+function numericId(value, what, hint = DISCOVERY_HINT) {
+    const id = wireInteger(value, what, hint);
+    if (!Number.isSafeInteger(id)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} has an id that is not a usable whole number (${describeIdValue(value)})`), undefined, { retryable: false, hint });
+    }
+    return id;
+}
+/**
+ * What a wire value IS, for a site that was not reading an id.
+ *
+ * `describeIdValue` speaks about ids — "out of safe integer range", "not whole"
+ * — and reusing it for containers and text produced messages that send a reader
+ * hunting for the wrong thing: "the project dock is out of safe integer range
+ * rather than a list" for `{"dock": 5}`.
+ */
+function describeWireValue(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "object")
+        return "an object";
+    return `${typeof value} ${String(value)}`;
+}
+function describeIdValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    // `typeof []` is "object", which names neither of the two shapes a caller
+    // would have to tell apart to fix the response.
+    if (Array.isArray(value))
+        return "an array";
+    if (typeof value === "number") {
+        // Two different complaints, and the first version made both of them the
+        // second: 1.5 is perfectly in range and was carried faithfully — what is
+        // wrong with it is that it is not whole. A value past 2^53 is the other
+        // case, and there the number has already been rounded by JSON.parse, so
+        // quoting it would report something the response never carried.
+        if (Number.isInteger(value))
+            return "out of safe integer range";
+        return `${value}, which is not whole`;
+    }
+    return typeof value;
+}
+/**
+ * Whether an error is a read's own 404 — the one answer discovery treats as
+ * "not here".
+ *
+ * The status is required, not just the code. Go reaches this through a
+ * `*basecamp.Error` whose `CodeNotFound` can only have come from a 404
+ * response; here `not_found` is also the code {@link UnresolvedRecordingError}
+ * carries, deliberately statusless. Matching on the code alone would let a
+ * composite's own verdict — thrown by a hook, a middleware, or a caller-supplied
+ * read source — be read as "the line is not in this Campfire", and discovery
+ * would move on and eventually report the line unresolved instead of surfacing
+ * it. Every `not_found` the transport produces carries the status.
+ */
+function isNotFound(err) {
+    return isBasecampError(err) && err.code === "not_found" && err.httpStatus === 404;
+}
+/** One `summarize` call's discovery state. */
+class ChatLineSearch {
+    sources;
+    lineId;
+    /** Candidates that answered 404, in order. */
+    tried = [];
+    /** Candidates still allowed. */
+    budget = MAX_CAMPFIRE_CANDIDATES;
+    /** Whether a candidate was left untried for want of budget. */
+    skipped = false;
+    constructor(sources, lineId) {
+        this.sources = sources;
+        this.lineId = lineId;
+    }
+    /**
+     * Reads the line under each candidate not yet tried. Returns the line and its
+     * Campfire on a hit; on a miss returns `undefined` and records the candidates
+     * in {@link tried}. Any answer but 404 is raised as is.
+     */
+    async try(candidates) {
+        for (const campfireId of candidates) {
+            if (this.tried.includes(campfireId))
+                continue;
+            if (this.budget <= 0) {
+                this.skipped = true;
+                return undefined;
+            }
+            this.budget--;
+            try {
+                const line = await this.sources.campfires.getLine(campfireId, this.lineId);
+                return { line, campfireId };
+            }
+            catch (err) {
+                if (isNotFound(err)) {
+                    this.tried.push(campfireId);
+                    continue;
+                }
+                throw err;
+            }
+        }
+        return undefined;
+    }
+}
+// =============================================================================
+// Service
+// =============================================================================
+/**
+ * `RecordingsService` with the hand-written `summarize` composite on top of the
+ * generated surface (`list`, `trash`, ...).
+ *
+ * The composite reaches its sibling reads through the client that built it, so
+ * every request is the same public generated method a caller would have made
+ * and hooks see each under its own operation identity.
+ */
+export class RecordingsService extends GeneratedRecordingsService {
+    #sources;
+    #campfires;
+    // Preserve BaseService's full positional signature, then append the read
+    // sources — the shape uploads-extensions established, so an existing
+    // `new RecordingsService(client, hooks, fetchPage, maxPages)` call keeps
+    // working and `summarize()` explains itself when the sources were not wired.
+    constructor(client, hooks, fetchPage, maxPages, authenticatedFetch, baseUrl, sources, now) {
+        super(client, hooks, fetchPage, maxPages, authenticatedFetch, baseUrl);
+        this.#sources = sources;
+        // The index lives on the service, which the client memoizes: the dock and
+        // listing snapshots are shared by every summarize() through one client and
+        // by nothing across two, which is the scope Go gives them on its Client.
+        this.#campfires = new CampfireIndex(now);
+    }
+    /**
+     * Resolves a recording pointer into a {@link RecordingSummary} through the
+     * typed read its type names. See {@link RecordingRef} for the routing inputs.
+     *
+     * Errors: a routing failure (`no_recording_type` / `unknown_recording_type`)
+     * before any request; the read's own {@link BasecampError} otherwise — a 404
+     * is `not_found`, as from the typed read itself; for chat lines,
+     * {@link UnresolvedRecordingError} when every visible Campfire answered 404,
+     * which is distinct from a read that failed (any non-404 from a candidate is
+     * raised as that error, and the loop stops there) and from
+     * {@link CampfireDiscoveryIncompleteError} (candidates were left unsearched);
+     * {@link BucketMismatchError} when the read returned a recording from another
+     * bucket.
+     *
+     * @example
+     * ```ts
+     * const summary = await client.recordings.summarize({
+     *   bucketId: 2085958499,
+     *   recordingId: 1069479361,
+     *   eventType: "comment.created",
+     * });
+     * summary.mentioned_person_ids; // [1049715915]
+     * ```
+     */
+    async summarize(ref) {
+        // `isSafeInteger`, not `isInteger`, and for two different reasons — one per
+        // id, both worth stating because a reader checking only the first would
+        // think the second was along for the ride.
+        //
+        // `recordingId` is ADDRESSED: it is interpolated into every read this
+        // composite makes, so a rounded value fetches a DIFFERENT recording and
+        // reports it as the one asked for. That is the same rule `numericId`
+        // applies to a Campfire id, at the other end of the same URL.
+        //
+        // `bucketId` is COMPARED — the listing's bucket filter and the cross-project
+        // check both weigh it against a number that arrived through JSON.parse, and
+        // two int64 buckets can round onto one double, which is how a recording from
+        // another project passed as a match — AND addressed, since chat-line
+        // discovery reads `/projects/{bucketId}`. An earlier version of this
+        // paragraph split the two ids by those two words, one each, in a commit
+        // whose whole point was that a reason had covered only half of a check. It
+        // covered half again.
+        //
+        // Go accepts both — its ids are int64 — so this is a refusal the reference
+        // does not make, and it is this port's, not a reading of SPEC waiver 1B.6:
+        // the waiver is about decoding ids the API sends, and says nothing about
+        // caller input. A `usage` error because the caller supplied the value, and
+        // a refusal rather than a silent rounding because the alternative is
+        // answering about a recording nobody asked for.
+        if (!Number.isSafeInteger(ref.bucketId) ||
+            ref.bucketId <= 0 ||
+            !Number.isSafeInteger(ref.recordingId) ||
+            ref.recordingId <= 0) {
+            throw Errors.usage("bucket id and recording id are required");
+        }
+        const kind = routeRecording(ref);
+        const summary = await this.#readSummary(ref, kind);
+        // A bucket the read did not identify is Go's zero value: there is nothing
+        // to disagree with, so the pointer stands rather than the call failing.
+        // The bucket itself, not only its id: a string or an array where the object
+        // belongs leaves `?.id` undefined, and "no bucket identified" is exactly the
+        // answer that lets a recording in another project pass as a match. Go fails
+        // the read on that body (measured: a string and an array are both decode
+        // errors into the bucket struct; a null is the zero value, hence absent).
+        // `"bucket" in summary`, not `!== undefined`: the projection assigns this
+        // key on truthiness, so `"bucket": 0`, `false` and `""` never became a key
+        // at all and slipped past a guard that asked whether the key was undefined.
+        // Each of them is a decode error in Go, and each read here as "no bucket
+        // identified" — the answer that lets a recording in another project pass as
+        // a match, arrived at through the one door the first guard left open.
+        const readBucket = summary.bucket;
+        if (readBucket !== undefined && (readBucket === null || typeof readBucket !== "object" || Array.isArray(readBucket))) {
+            throw Errors.apiError(truncateErrorMessage(`the recording read identified its bucket as ${describeWireValue(readBucket)}`), undefined, {
+                retryable: false,
+                hint: "the response is malformed; whether the recording is in the requested project cannot be decided from it",
+            });
+        }
+        // And the id, through the same gate as the three discovery sites — this one
+        // reached it last. It began as `!== undefined`, which read a malformed id as
+        // "no bucket"; then `typeof`, which still compared a FRACTION and could
+        // report the recording as living in bucket 1.5; then `isInteger`, which
+        // stopped fabricating that verdict but still answered "no bucket
+        // identified" for a string, a boolean, an array or an object — and that
+        // answer is the one that lets a recording in ANOTHER project pass as a
+        // match. Go refuses every one of those bodies outright, and `numericId`
+        // says exactly that: null and absent are its zero, which is skipped;
+        // anything else that is not a whole number in range fails the read.
+        // Go's line is `summary.Bucket != nil && summary.Bucket.ID != 0 &&
+        // summary.Bucket.ID != ref.BucketID` — the type half from its decoder, then
+        // a value rule of exactly "not zero, not the one asked for". `wireInteger`,
+        // not `numericId`: the safe-integer clause belongs to the sites that BUILD
+        // A URL from the id, where a rounded value addresses a different Campfire.
+        // Nothing is addressed here; the id is only compared.
+        //
+        // An argument for comparing rounded ids stood here until it was deleted.
+        // Not softened and not quoted: it argued for the behaviour two lines below
+        // it, and a reader weighing prose against code would have believed the
+        // prose. What replaced it lives in `summarize`, which refuses a caller id
+        // this runtime cannot hold exactly.
+        const readBucketId = wireInteger(summary.bucket?.id, "the recording read's bucket", RECORDING_HINT);
+        // `!Number.isSafeInteger` is a MISMATCH, not a pass — and, like the listing
+        // filter, unreachable while `ref.bucketId` must itself be a safe integer,
+        // since a rounded value above 2^53 cannot equal one below it. The fix for
+        // the defect is the check in `summarize`, not this clause; this states the
+        // same fact where the comparison happens, and a revert of it is
+        // behaviour-neutral.
+        //
+        // The defect: this used to compare the rounded values, with a comment
+        // arguing they "round identically, so the comparison still means
+        // something". It does not. Rounding is not injective, and a recording from
+        // bucket 2^53+1 came back as a MATCH for a request against 2^53 — the one
+        // thing this check exists to prevent, argued for in prose.
+        if (readBucketId !== 0 && (!Number.isSafeInteger(readBucketId) || readBucketId !== ref.bucketId)) {
+            throw new BucketMismatchError(ref, readBucketId);
+        }
+        return summary;
+    }
+    /** The sources, or a usage error naming how to obtain a wired service. */
+    get #reads() {
+        const sources = this.#sources?.();
+        if (sources === undefined) {
+            throw Errors.usage("recordings.summarize composes the other services' reads — obtain RecordingsService via createBasecampClient(...).recordings rather than instantiating it directly");
+        }
+        return sources;
+    }
+    /** Performs the one typed read a kind names and projects it. */
+    async #readSummary(ref, kind) {
+        const reads = this.#reads;
+        const id = ref.recordingId;
+        switch (kind) {
+            case "comment": {
+                const c = recordingBody(await reads.comments.get(id));
+                return projectRecording(c, c.title, c.content, { parent: c.parent, bucket: c.bucket, creator: c.creator });
+            }
+            case "message": {
+                const m = recordingBody(await reads.messages.get(id));
+                return projectRecording(m, firstNonEmpty("a message title", m.title, m.subject), m.content, {
+                    parent: m.parent,
+                    bucket: m.bucket,
+                    creator: m.creator,
+                });
+            }
+            case "todo": {
+                // A to-do's content is its plain title; the rich text — where mentions
+                // live — is the description.
+                const t = recordingBody(await reads.todos.get(id));
+                return projectRecording(t, firstNonEmpty("a recording title", t.title, t.content), t.description, {
+                    parent: t.parent,
+                    bucket: t.bucket,
+                    creator: t.creator,
+                    assignees: t.assignees,
+                    // A todo carries a TodoParent, which has no bucket field at all.
+                    parentHasBucket: false,
+                });
+            }
+            case "card": {
+                const c = recordingBody(await reads.cards.get(id));
+                return projectRecording(c, c.title, firstNonEmpty("a recording rich text", c.content, c.description), {
+                    parent: c.parent,
+                    bucket: c.bucket,
+                    creator: c.creator,
+                    assignees: c.assignees,
+                });
+            }
+            case "chatLine": {
+                const { line: rawLine, campfireId } = await this.#resolveChatLine(ref.bucketId, id);
+                const line = recordingBody(rawLine);
+                const summary = projectRecording(line, line.title, line.content, {
+                    parent: line.parent,
+                    bucket: line.bucket,
+                    creator: line.creator,
+                });
+                if (!chatLineIsRichText(line.type)) {
+                    // A plain-text or code line's content is text BC3 never read as
+                    // markup, so a literal "<bc-attachment>" in it mentions nobody.
+                    summary.mentioned_person_ids = [];
+                    // And no unnameable ones either: the rich-text walk ran over `content`
+                    // before this branch knew the line was not rich text, so it may have
+                    // found a "mention" here. There is none -- this text mentions nobody,
+                    // in Go and here -- and leaving the key would report a short list
+                    // where there is no list at all.
+                    delete summary.unnameable_mention_ids;
+                }
+                // Omitted when zero, because Go's field is `omitempty` and a zero
+                // marshals away there. A zero is reachable: the account listing keeps
+                // an entry whose own id is null as a candidate (Go filters that source
+                // on the bucket alone), so a Campfire 0 that answers 200 resolves the
+                // line — and only then do the two SDKs' JSON differ by a key.
+                if (campfireId !== 0)
+                    summary.campfire_id = campfireId;
+                return summary;
+            }
+            case "document": {
+                const d = recordingBody(await reads.documents.get(id));
+                return projectRecording(d, d.title, d.content, { parent: d.parent, bucket: d.bucket, creator: d.creator });
+            }
+            case "upload": {
+                const u = recordingBody(await reads.uploads.get(id));
+                return projectRecording(u, firstNonEmpty("an upload title", u.title, u.filename), u.description, {
+                    parent: u.parent,
+                    bucket: u.bucket,
+                    creator: u.creator,
+                });
+            }
+            case "scheduleEntry": {
+                const e = recordingBody(await reads.schedules.getEntry(id));
+                return projectRecording(e, firstNonEmpty("a recording title", e.title, e.summary), e.description, {
+                    parent: e.parent,
+                    bucket: e.bucket,
+                    creator: e.creator,
+                });
+            }
+            case "question": {
+                const q = recordingBody(await reads.checkins.getQuestion(id));
+                return projectRecording(q, q.title, "", { parent: q.parent, bucket: q.bucket, creator: q.creator });
+            }
+            case "questionAnswer": {
+                const a = recordingBody(await reads.checkins.getAnswer(id));
+                return projectRecording(a, a.title, a.content, { parent: a.parent, bucket: a.bucket, creator: a.creator });
+            }
+            case "todolist": {
+                const l = recordingBody(await reads.todolists.get(id));
+                return projectRecording(l, firstNonEmpty("a recording title", l.title, l.name), l.description, {
+                    parent: l.parent,
+                    bucket: l.bucket,
+                    creator: l.creator,
+                    // A todolist carries a TodoParent too — same shape, same absence.
+                    parentHasBucket: false,
+                });
+            }
+            case "vault": {
+                const v = recordingBody(await reads.vaults.get(id));
+                return projectRecording(v, v.title, "", { parent: v.parent, bucket: v.bucket, creator: v.creator });
+            }
+            case "forward": {
+                const f = recordingBody(await reads.forwards.get(id));
+                return projectRecording(f, firstNonEmpty("a message title", f.title, f.subject), f.content, {
+                    parent: f.parent,
+                    bucket: f.bucket,
+                    creator: f.creator,
+                });
+            }
+            case "clientApproval": {
+                const a = recordingBody(await reads.clientApprovals.get(id));
+                return projectRecording(a, firstNonEmpty("a message title", a.title, a.subject), a.content, {
+                    parent: a.parent,
+                    bucket: a.bucket,
+                    creator: a.creator,
+                });
+            }
+            case "clientCorrespondence": {
+                const c = recordingBody(await reads.clientCorrespondences.get(id));
+                return projectRecording(c, firstNonEmpty("a message title", c.title, c.subject), c.content, {
+                    parent: c.parent,
+                    bucket: c.bucket,
+                    creator: c.creator,
+                });
+            }
+            case "googleDocument": {
+                const g = recordingBody(await reads.googleDocuments.googleDocument(id));
+                return projectRecording(g, g.title, g.description, { parent: g.parent, bucket: g.bucket, creator: g.creator });
+            }
+            case "cloudFile": {
+                const f = recordingBody(await reads.cloudFiles.cloudFile(id));
+                return projectRecording(f, f.title, f.description, { parent: f.parent, bucket: f.bucket, creator: f.creator });
+            }
+            case "cardStep": {
+                const s = recordingBody(await reads.cardSteps.get(id));
+                return projectRecording(s, s.title, "", {
+                    parent: s.parent,
+                    bucket: s.bucket,
+                    creator: s.creator,
+                    assignees: s.assignees,
+                });
+            }
+            case "questionnaire": {
+                const q = recordingBody(await reads.checkins.getQuestionnaire(id));
+                return projectRecording(q, firstNonEmpty("a recording title", q.title, q.name), "", { bucket: q.bucket, creator: q.creator });
+            }
+            case "schedule": {
+                const s = recordingBody(await reads.schedules.get(id));
+                return projectRecording(s, s.title, "", { bucket: s.bucket, creator: s.creator });
+            }
+            case "todoset": {
+                const t = recordingBody(await reads.todosets.get(id));
+                return projectRecording(t, firstNonEmpty("a recording title", t.title, t.name), "", { bucket: t.bucket, creator: t.creator });
+            }
+            case "messageBoard": {
+                const b = recordingBody(await reads.messageBoards.get(id));
+                return projectRecording(b, b.title, "", { bucket: b.bucket, creator: b.creator });
+            }
+            case "cardTable": {
+                const t = recordingBody(await reads.cardTables.get(id));
+                return projectRecording(t, t.title, "", { bucket: t.bucket, creator: t.creator });
+            }
+            case "cardColumn": {
+                const c = recordingBody(await reads.cardColumns.get(id));
+                return projectRecording(c, c.title, c.description, {
+                    parent: c.parent,
+                    bucket: c.bucket,
+                    creator: c.creator,
+                });
+            }
+            case "inbox": {
+                const i = recordingBody(await reads.forwards.getInbox(id));
+                return projectRecording(i, i.title, "", { bucket: i.bucket, creator: i.creator });
+            }
+            case "campfire": {
+                const c = recordingBody(await reads.campfires.get(id));
+                return projectRecording(c, c.title, "", { bucket: c.bucket, creator: c.creator });
+            }
+            default:
+                // Unreachable for a routed kind — the switch is exhaustive over
+                // SummaryKind — and kept anyway, as Go keeps its trailing routing
+                // error. Without it a value that reached here outside the type system
+                // would fall out of the switch as `undefined` and be dereferenced as a
+                // summary, turning a routing failure into a TypeError.
+                throw new RecordingRoutingError(ref, "unknown_recording_type");
+        }
+    }
+    /**
+     * Finds the Campfire a line lives in and reads it.
+     *
+     * A `chat.line.created` row carries the line's id and bucket, not its
+     * Campfire, and the line read is `/chats/{campfireId}/lines/{lineId}`.
+     * Candidates come from two sources, tried in order and each cached ten
+     * minutes:
+     *
+     * 1. The bucket's project dock, whose `chat` tool is the project's Campfire:
+     *    one project read per bucket, and the answer for every line posted in a
+     *    project. Cached per bucket.
+     * 2. The account-wide Campfire listing (BC3 has no per-bucket one), filtered
+     *    to the bucket, for buckets that are not projects or whose dock did not
+     *    hold the line. Cached per account, so a burst of lines costs one
+     *    listing.
+     *
+     * The loop tries the line under each candidate until one answers, within one
+     * total budget of {@link MAX_CAMPFIRE_CANDIDATES} per call.
+     *
+     * Two failure shapes are kept apart on purpose. A candidate that answers
+     * anything but 404 — 401, 403, 5xx, a network error — stops the loop and is
+     * raised as that error: the read failed, and trying the next Campfire would
+     * only hide it. A 404 means "not here", so the loop moves on. Only when every
+     * candidate said "not here" is the line unresolved
+     * ({@link UnresolvedRecordingError}) — and before concluding that, the cached
+     * sources are refreshed (subject to the floor) so a Campfire created after
+     * the cache filled is tried too. Discovery that could not be completed — a
+     * listing cut off at its cap, a bucket with more candidates than the budget —
+     * is {@link CampfireDiscoveryIncompleteError}, never "unresolved": nothing
+     * unsearched is ever reported absent — which is why a spent budget is read
+     * against WHICH sources it was spent before: one already consulted is simply
+     * not re-read, while one never reached leaves candidates unsearched and makes
+     * the verdict incomplete.
+     *
+     * What HTTP cannot tell apart: BC3 answers 404 both for a line that is not in
+     * a Campfire and for a Campfire the caller may no longer see. "Unresolved"
+     * therefore means "under no Campfire the caller can currently see", and the
+     * error reports the cached candidates that the refreshed sources no longer
+     * list ({@link UnresolvedRecordingError.staleCampfireIds}) so a consumer can
+     * see when visibility, not existence, is what changed.
+     */
+    async #resolveChatLine(bucketId, lineId) {
+        const reads = this.#reads;
+        const index = this.#campfires;
+        const search = new ChatLineSearch(reads, lineId);
+        const incomplete = (reason) => new CampfireDiscoveryIncompleteError({ bucketId, recordingId: lineId, reason });
+        // Pass 1: what the sources already hold — the dock (read if it must be),
+        // then the listing only if it is cached. A listing fetch is the expensive,
+        // slow request, and it is not made until the dock — including its refresh —
+        // has had its say, so a listing that is down or over its cap never stands
+        // between a project's line and the one project read that finds it.
+        let dock = await index.dockCampfires(reads, bucketId, false);
+        const fromDock = await search.try(dock.ids);
+        if (fromDock !== undefined)
+            return fromDock;
+        let listed = index.cachedListedCampfires(bucketId);
+        const listCached = listed !== undefined;
+        if (listed !== undefined) {
+            const fromCachedListing = await search.try(listed.ids);
+            if (fromCachedListing !== undefined)
+                return fromCachedListing;
+        }
+        // Pass 2: re-read the dock if it was served from cache (the floor may
+        // decline), then fetch or refresh the listing. Whatever comes back is the
+        // current snapshot of that source, whoever loaded it — another caller may
+        // have populated or refreshed it in the meantime — so it always replaces
+        // the pass-1 one; "refreshed" is whether a source the conclusion had
+        // consulted is now newer than when it was consulted.
+        //
+        // Not when the budget is already spent: a re-read could return no candidate
+        // this call may try, so it would cost a request that cannot help — and a
+        // failure on it would replace the deterministic "incomplete" verdict with a
+        // transient error a consumer retries forever.
+        let refreshed = false;
+        // No budget left means no re-read: a source already consulted cannot hand
+        // this call a candidate it may try, so its refresh is skipped and the
+        // conclusion stands on what was seen (refreshed false). A source NEVER
+        // consulted is different — candidates may exist there unsearched — so
+        // running out of budget before reaching it makes the verdict incomplete.
+        //
+        // Concluding incomplete on a spent budget unconditionally would be the
+        // wrong fix: it would call a search that did examine both sources
+        // unfinished. Concluding nothing would be the other wrong fix, and is what
+        // this replaced — it fetched a listing that could not help, and a failure
+        // on that fetch replaced a deterministic "incomplete" with a transient
+        // error a consumer retries forever.
+        if (search.budget > 0 && dock.cached) {
+            const again = await index.dockCampfires(reads, bucketId, true);
+            if (again.fetchedAt > dock.fetchedAt || !again.cached)
+                refreshed = true;
+            dock = again;
+            const fromRefreshedDock = await search.try(dock.ids);
+            if (fromRefreshedDock !== undefined)
+                return fromRefreshedDock;
+        }
+        if (search.budget <= 0) {
+            if (!listCached) {
+                throw incomplete(`the candidate budget of ${MAX_CAMPFIRE_CANDIDATES} was spent before the account listing was consulted`);
+            }
+        }
+        else {
+            let again;
+            try {
+                again = await index.listedCampfires(reads, bucketId, listCached);
+            }
+            catch (err) {
+                if (err instanceof CampfireListingOverflow)
+                    throw incomplete(err.message);
+                throw err;
+            }
+            if (listed !== undefined && (again.fetchedAt > listed.fetchedAt || !again.cached)) {
+                refreshed = true;
+            }
+            listed = again;
+            const fromListing = await search.try(listed.ids);
+            if (fromListing !== undefined)
+                return fromListing;
+        }
+        if (search.skipped) {
+            throw incomplete(`more than ${MAX_CAMPFIRE_CANDIDATES} visible campfires in the bucket`);
+        }
+        const listedIds = listed?.ids ?? [];
+        const staleCampfireIds = refreshed
+            ? search.tried.filter((id) => !dock.ids.includes(id) && !listedIds.includes(id))
+            : [];
+        throw new UnresolvedRecordingError({
+            bucketId,
+            recordingId: lineId,
+            campfireIds: search.tried,
+            refreshed,
+            staleCampfireIds,
+        });
+    }
+}
+/** Builds the projection, keeping only the keys the recording actually has. */
+function projectRecording(recording, title, content, nested) {
+    const body = recordingText(content, "a recording rich text");
+    // The scalars default rather than carrying `undefined` through: they are
+    // required on every routed shape, so a body omitting one is malformed, and
+    // Go emits its zero value. Left undefined, JSON.stringify would drop the key
+    // and a consumer would see a shape no other SDK produces. The three strings
+    // default to ""; updated_at does not, because its Go type is not a string.
+    const summary = {
+        // `id` too, which the first pass at this missed even while the comment
+        // above stated the rule: Go marshals a zero RecordingSummary as {"id":0,…}.
+        // And through `wireInteger`, which the id sweep missed here while sweeping
+        // the three discovery sites and every string field around it: this was the
+        // one number field left on a bare `??`, so `{"id":"1"}` came back as the
+        // STRING "1" in a field typed `number`, a shape no other SDK can produce.
+        // `wireInteger`, not `numericId`: this id is emitted, never addressed.
+        id: wireInteger(recording.id, "the recording", RECORDING_HINT),
+        status: recordingText(recording.status, "a recording status"),
+        type: recordingText(recording.type, "a recording type"),
+        // The types that read `title` straight off the recording pass it through
+        // undefined when the body omits it; the ones with a fallback already
+        // resolve to "" through firstNonEmpty.
+        title: recordingText(title, "a recording title"),
+        app_url: recordingText(recording.app_url, "a recording app_url"),
+        ...mentionsOf(body),
+        content: body,
+        // Go's zero value here is a `time.Time`, not a string, and it marshals as
+        // the zero instant rather than as "".
+        updated_at: recordingInstant(recording.updated_at),
+    };
+    // Each nested identity through the same gate as the bucket, and for the same
+    // reason the sweep gave when it stopped at the bucket: measured through
+    // generated.Comment and generated.Todo, a number, a string, a boolean or an
+    // array in any of these slots is a decode error, while null and {} are the
+    // zero value. Two of the four had no rule at all, three lines from the one
+    // that did — the sweep stopped one field short of where it said it stopped.
+    const parent = withEmptyLabel(nestedIdentity(nested.parent, "a recording parent", "parent", nested.parentHasBucket ?? true), "title");
+    if (parent !== undefined)
+        summary.parent = parent;
+    // Assigned when PRESENT, not when truthy: a falsy non-object (0, false, "")
+    // is a decode error in Go, and dropping the key here hid it from the
+    // cross-project check, which then found nothing to disagree with. Its own
+    // fields go through the same gate as every other member's; the id stays with
+    // the cross-project check below, which is the one place it is INTERPRETED
+    // rather than reported.
+    if (nested.bucket !== undefined && nested.bucket !== null) {
+        // The RETURN value, not the original: the bucket arm decodes its id the way
+        // the parent arm does, and calling it for its refusals alone dropped the
+        // conversion on the floor — so a null bucket id stayed `null` where Go and
+        // Ruby both give 0. The first spelling of this line did exactly that.
+        //
+        // No nullish fallback, for the reason the assignees paragraph below gives:
+        // the guard above has already excluded the only two inputs for which
+        // `nestedIdentity` returns `undefined`, so a `?? nested.bucket` here was
+        // unreachable — and it fell back to the ORIGINAL, the very thing the
+        // sentence above says not to emit. A mutation replacing it with a cast left
+        // the whole suite green, which is what an unreachable branch looks like.
+        summary.bucket = withEmptyLabel(nestedIdentity(nested.bucket, "a recording bucket", "bucket"), "name");
+    }
+    const creator = withEmptyLabel(nestedIdentity(nested.creator, "a recording creator", "person"), "name");
+    if (creator !== undefined)
+        summary.creator = creator;
+    // `assignees` is a LIST of them: Go refuses a non-array and a non-object
+    // element, and takes null as the nil slice. Go's own `omitempty` is why an
+    // empty list is dropped rather than emitted.
+    // `wireItems` does the whole job: absent and null are the empty list, a
+    // non-array fails the read, and each element goes through the same object
+    // check the other three identities use. An earlier spelling wrapped every
+    // element in `nestedIdentity` as well and credited the elementwise refusal to
+    // it — that call could refuse nothing, having been handed an object already.
+    const assignees = wireItems(nested.assignees, "a recording assignees list");
+    // Each element through the SAME Person gate the creator takes. Go decodes
+    // `[]Person`, so a wrong-typed `avatar_url` on the second assignee fails its
+    // read exactly as it does on the first — and a rule applied to the creator
+    // but not to the assignees would be the same inconsistency one level out.
+    // Mapped rather than walked in place: the flexible id CONVERTS, so an element
+    // whose id arrived as "007" has to be replaced by the decoded one.
+    //
+    // No nullish fallback on the result, and that is not an oversight: `wireItems`
+    // has already mapped a null or absent element to `{}` (see `sourceObject`),
+    // so nothing nullish reaches `nestedIdentity` and its `undefined` branch is
+    // unreachable from here. A `?? assignee` here READ as if it were preserving a
+    // null element Go emits as the zero Person, and preserved nothing — a guard
+    // whose only effect was to make a reader believe a case was handled.
+    const typedAssignees = assignees.map((assignee) => nestedIdentity(assignee, "a recording assignee", "person"));
+    if (typedAssignees.length > 0)
+        summary.assignees = typedAssignees;
+    return summary;
+}
+function firstNonEmpty(what, ...values) {
+    // EVERY candidate, not just the ones reached. Go's decoder refuses a
+    // wrong-typed field whether or not the projection goes on to use it, so
+    // `{"title":"T","subject":42}` fails the read there while a short-circuit
+    // here returned "T" and never looked at the subject. Validate first, choose
+    // after.
+    const texts = values.map((value) => recordingText(value, what));
+    for (const value of texts) {
+        // A JSON null reads as Go's zero value and falls THROUGH to the next
+        // candidate. Treating null as present is the quiet version of this defect:
+        // {"title":null,"subject":"S"} decodes in Go with an empty title and takes
+        // the subject, while here null passed the test, was returned, and the
+        // caller's `?? ""` turned it into "" — the fallback lost, and a message
+        // summarized under no title at all.
+        if (value !== "")
+            return value;
+    }
+    return "";
+}
+/** Go's zero `time.Time`, which is what it marshals for an absent instant. */
+const ZERO_INSTANT = "0001-01-01T00:00:00Z";
+// Measured against Go's decoder rather than read off RFC 3339, in three places
+// where it is wider than the grammar suggests: the fraction may be separated by
+// a COMMA as well as a dot (`…05,5Z` decodes, and re-marshals as `.5`); the
+// offset's range is wider than a clock, hour 00 to 24 and minute 00 to 60, with
+// 25 and 61 refused; and the HOUR is the one field Go parses at variable width
+// (`stdHour` calls `getnum` with `fixed=false`), so `T3:04:05Z` decodes and
+// re-marshals as `T03:04:05Z`. Measured alongside it: a single-digit month,
+// day, minute, second or offset component is refused, so `\d{1,2}` belongs to
+// the hour alone.
+const RFC3339 = /^(\d{4})-(\d{2})-(\d{2})T(\d{1,2}):(\d{2}):(\d{2})(?:[.,]\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/;
+/**
+ * The instant a routed read carries, refused when it is not one.
+ *
+ * `updated_at` is the exception among the projected scalars, and treating it as
+ * one more string got it wrong in both directions. Its Go type is `time.Time`,
+ * whose `UnmarshalJSON` is stricter than a string's: a JSON null is the zero
+ * instant and no error, but `""`, `"not-a-date"`, `"2024-01-02 03:04:05"`,
+ * `"2024-02-30T…"` and a lowercase `t` or `z` are all decode errors. The
+ * previous spelling — the string rule, then `|| ZERO_INSTANT` — painted `""`
+ * with the zero instant, so a body the reference REFUSES came back carrying a
+ * plausible timestamp instead of a visibly empty one.
+ *
+ * What this does not model is the re-rendering: Go parses and re-marshals, so
+ * `2024-01-02T03:04:05.000Z` comes back as `…:05Z` there and verbatim here, and
+ * `T3:04:05Z` as `T03:04:05Z`. The conformance runner compares instants rather
+ * than strings — but only for the forms its own regex admits, and these are not
+ * all of them. Six FAMILIES of accepted spelling render differently here than in
+ * Go, counted by rule and measured one spelling at a time, because the previous
+ * two attempts at this list both counted a rule by one of its examples:
+ *
+ * - **the fraction, normalized** — not "a comma becomes a dot", which is how
+ *   this was written and is one example of it. Go re-renders `.500Z` as `.5Z`,
+ *   `.000000000Z` as `Z`, and `,50Z` as `.5Z`: trailing zeros go, an all-zero
+ *   fraction goes entirely, and the separator is incidental;
+ * - a single-digit hour (`T3:`), re-rendered `T03:`, with or without an offset;
+ * - an offset hour of 24 (`+24:00`, and its twin `-24:00`), which Go's ENCODER
+ *   then refuses outright, its own range being [0,23];
+ * - an offset minute of 60 that stays within the hour (`+00:60` → `+01:00`);
+ * - an offset minute of 60 that CARRIES (`+23:60` → hour 24), which Go decodes
+ *   and then cannot marshal at all;
+ * - a zero offset (`+00:00`, `-00:00`), which Go re-renders as `Z`.
+ *
+ * Where each one lands in the runner differs, and "all of them fall back to
+ * exact string comparison" — the previous claim — is false for two. `T3:` and a
+ * comma fail `sameInstant`'s regex; the offset-24 and carry forms match it and
+ * fail its `Date.parse` guard; a normalized fraction reaches its
+ * `fractionalDigits` comparison, which is the one that would actually FAIL a
+ * fixture carrying `.500Z`; and a zero offset compares EQUAL, so that family is
+ * genuinely invisible rather than merely unexercised.
+ *
+ * The zero instant is not on this list and was: `0001-01-01T00:00:00Z` is what
+ * Go emits and what this returns, it round-trips identically, and it passes the
+ * runner's regex, its `isRealTimestamp` year clause and `Date.parse`. A list of
+ * things that differ is the wrong place for the one value both sides agree on. Nothing in the fixture carries one — checked, every
+ * `updated_at` there is canonical — so the difference is invisible in practice
+ * rather than by construction.
+ *
+ * Accepting them is still right: refusing a body the reference reads is the
+ * worse error, and this composite reports what the API served. The leniency is
+ * the stdlib's own — `format_rfc3339.go` disables strict parsing behind a
+ * `case true:` and a TODO about a GODEBUG opt-out — so if that lands, these
+ * become decode errors there and this rule follows the measurement again.
+ */
+function recordingInstant(value) {
+    if (value === undefined || value === null)
+        return ZERO_INSTANT;
+    const text = recordingText(value, "a recording updated_at");
+    const parts = RFC3339.exec(text);
+    if (parts !== null) {
+        const year = Number(parts[1]);
+        const month = Number(parts[2]);
+        const day = Number(parts[3]);
+        const hour = Number(parts[4]);
+        const minute = Number(parts[5]);
+        const second = Number(parts[6]);
+        const offsetHour = parts[7] === undefined ? 0 : Number(parts[7]);
+        const offsetMinute = parts[8] === undefined ? 0 : Number(parts[8]);
+        // The shape is not enough: 2024-02-30 and 25:04 match it and Go refuses
+        // them. A UTC round-trip is what rejects a date the calendar does not have
+        // — with `setUTCFullYear` after it, because `Date.UTC(1, …)` means 1901,
+        // not year 1, and the two-digit-year mapping made this refuse
+        // "0001-01-01T00:00:00Z": THE ZERO INSTANT, the value Go marshals for an
+        // absent time and the one this very function returns for a null. It was not
+        // idempotent on its own output.
+        const at = new Date(Date.UTC(2000, month - 1, day, hour, minute, second));
+        at.setUTCFullYear(year);
+        if (at.getUTCFullYear() === year &&
+            at.getUTCMonth() === month - 1 &&
+            at.getUTCDate() === day &&
+            at.getUTCHours() === hour &&
+            at.getUTCMinutes() === minute &&
+            at.getUTCSeconds() === second &&
+            offsetHour <= 24 &&
+            offsetMinute <= 60) {
+            return text;
+        }
+    }
+    throw Errors.apiError(truncateErrorMessage(`a recording updated_at is ${describeWireValue(value)} rather than an RFC 3339 instant`), undefined, { retryable: false, hint: "the response is malformed; the recording cannot be summarized from it" });
+}
+/**
+ * The fields of a nested member the reference types, by the model it decodes
+ * into.
+ *
+ * TRANSCRIBED FROM `generated`, NOT FROM `pkg/basecamp`, and the difference is
+ * load-bearing rather than pedantic. The Go service wrapper the composite calls
+ * hands the body to the GENERATED client and converts afterwards
+ * (`commentFromGenerated`), so the decode — the thing that fails a read —
+ * happens against the generated model. The two disagree in exactly the two
+ * places that would have bitten: `system_label` is a field of the hand-written
+ * Person and NOT of the generated one, so it is an unknown key the reference
+ * IGNORES and typing it here would refuse a body the reference accepts; and a
+ * person's id is `FlexibleInt64` there against a plain `int64` here.
+ *
+ * `created_at` / `updated_at` are `*time.Time` in Go: a non-string fails on
+ * both sides, and a string that is not RFC 3339 fails only there. That residue
+ * is declared rather than closed, alongside the recording's own unread
+ * top-level fields.
+ */
+const PERSON_STRING_FIELDS = [
+    "attachable_sgid",
+    "avatar_url",
+    "bio",
+    "created_at",
+    "email_address",
+    "location",
+    "name",
+    "personable_type",
+    "tagline",
+    "time_zone",
+    "title",
+    "updated_at",
+];
+const PERSON_BOOL_FIELDS = [
+    "admin",
+    "can_access_hill_charts",
+    "can_access_timesheet",
+    "can_manage_people",
+    "can_manage_projects",
+    "can_ping",
+    "client",
+    "employee",
+    "owner",
+];
+const PARENT_STRING_FIELDS = ["title", "type", "url", "app_url"];
+const BUCKET_STRING_FIELDS = ["name", "type"];
+/** Go's int64 window, the bound `FlexibleInt64` decodes within. */
+const INT64_MAX = 9223372036854775807n;
+const INT64_MIN = -9223372036854775808n;
+function memberString(member, field, what) {
+    const value = member[field];
+    // NULL IS NOT A WRONG TYPE. Every one of these is a `*string` or a plain
+    // `string` in the model and `json.Unmarshal` of `null` is a no-op at any
+    // depth, so only a PRESENT value of the wrong type fails.
+    if (value === undefined || value === null || typeof value === "string")
+        return;
+    throw Errors.apiError(truncateErrorMessage(`${what} ${field} is ${describeWireValue(value)} rather than a string`), undefined, { retryable: false, hint: "the response is malformed; the recording cannot be summarized from it" });
+}
+function memberBool(member, field, what) {
+    const value = member[field];
+    // `1` does NOT pass. JavaScript would read it as truthy; Go refuses a number
+    // for a bool outright, and this is the read side of a payload nobody here
+    // wrote.
+    if (value === undefined || value === null || typeof value === "boolean")
+        return;
+    throw Errors.apiError(truncateErrorMessage(`${what} ${field} is ${describeWireValue(value)} rather than a boolean`), undefined, { retryable: false, hint: "the response is malformed; the recording cannot be summarized from it" });
+}
+/**
+ * A person's `company`: `PersonCompany{Id int64, Name string}`.
+ *
+ * Its id takes the PLAIN reader, not the flexible one the person's own id
+ * takes — `{"company":{"id":"1"}}` fails the read in the reference where
+ * `{"id":"1"}` on the person beside it resolves.
+ */
+function memberCompany(member, what) {
+    const company = member["company"];
+    if (company === undefined || company === null)
+        return;
+    if (typeof company !== "object" || Array.isArray(company)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} company is ${describeWireValue(company)} rather than an object`), undefined, { retryable: false, hint: "the response is malformed; the recording cannot be summarized from it" });
+    }
+    const fields = company;
+    wireInteger(fields["id"], `${what} company`, RECORDING_HINT);
+    memberString(fields, "name", `${what} company`);
+}
+/**
+ * `types.FlexibleInt64`, which is what a person's id — and only a person's id —
+ * decodes through in the generated model.
+ *
+ * It differs from a plain `int64` in three directions that are easy to get
+ * backwards, all measured against the reference rather than inferred:
+ *
+ *   - a NON-NUMERIC string is 0, not an error. That 0 is the system-actor
+ *     sentinel ("basecamp", "campfire"), so reading it as a person id would
+ *     name a real person where Go names no one.
+ *   - `null` IS an error here, where a plain int64 field reads it as 0:
+ *     `FlexibleInt64.UnmarshalJSON` is called for null and decodes it as a
+ *     number.
+ *   - the int64 WINDOW still applies to both forms. A number is not exempt
+ *     from it because it arrived as a number: `1e20` and `9223372036854775808`
+ *     are `flexibleint64: not a valid int64` in the reference, and an earlier
+ *     spelling of this function bounded the string branch and left the number
+ *     branch on a bare `Number.isInteger` — the same clause `wireInteger` four
+ *     definitions above already carries, dropped in a copy of its own policy.
+ *
+ * It CONVERTS as well as validates, and the conversion is the half TypeScript
+ * was missing: `"007"` is 7 in the summary Go hands back, so validating the
+ * string and then emitting it left this port's projection a different shape
+ * from the contract it shares — a `creator.id` of type `string` where the other
+ * six SDKs emit a number.
+ *
+ * WHAT REACHES THIS READER, which is narrower than it looks and which two
+ * rounds of review were needed to state correctly. `normalizePersonIds`
+ * (`services/base.ts`) runs over every response body before any composite sees
+ * it, and rewrites the `id` of any object carrying `personable_type` — a
+ * numeric string in safe range becomes the number, and anything else becomes
+ * `0` plus a manufactured `system_label`. Every real BC3 person carries
+ * `personable_type`, so on a realistic body the conversion below has already
+ * happened upstream. This reader governs the person objects that LACK it,
+ * which is where this port used to emit `"007"` as a string.
+ *
+ * THREE RESIDUES, declared because this runtime cannot close them and because
+ * two earlier versions of this comment called a shorter list exhaustive:
+ *
+ *   - `7.0` is accepted as 7. `JSON.parse` cannot see the fraction, so nothing
+ *     at this layer can tell it from `7`, while Go's decoder reads the raw
+ *     bytes and refuses it. Ruby and Python both refuse it; this port cannot.
+ *   - `created_at` / `updated_at` are `*time.Time` in the model, so Go refuses
+ *     an unparseable string as well as a non-string. This port checks only the
+ *     TYPE, the same residue Ruby's `#read_member_fields` and its SPEC row
+ *     declare for the same two fields.
+ *   - an id past `Number.MAX_SAFE_INTEGER` is REFUSED here rather than rounded.
+ *     The reference accepts `"9223372036854775807"` and carries it exactly;
+ *     JavaScript cannot, and `Number(BigInt("9223372036854775807"))` is 2^63 —
+ *     a value this function's own overflow guard exists to reject, arrived at
+ *     one line after passing it. Refusing is the direction that does not hand a
+ *     caller a person id naming someone else.
+ *
+ *     This is deliberately STRICTER than the sibling ids, and the inconsistency
+ *     is stated rather than smoothed over: `summary.id` and `parent.id` emit
+ *     the rounded value under retained waiver 1B.6, and an earlier version of
+ *     this paragraph claimed the refusal was "the rule `numericId` and
+ *     `summarize` already apply", which it is not — those two apply it to ids
+ *     that ADDRESS something and to ids the CALLER supplied. The argument for
+ *     the stricter rule here is only that a person id names a person; whether
+ *     1B.6 should be revisited for the others is its own question and not
+ *     this change's to answer.
+ *
+ *     Where the pre-pass above DID run, this branch is unreachable and the
+ *     caller has already been handed `0` and a `system_label` the reference
+ *     never emits. That is a divergence in `normalizePersonIds` rather than in
+ *     this composite, it is SDK-wide rather than local to the summary, and it
+ *     is recorded on card 39 for the person-id card rather than patched here.
+ */
+function flexiblePersonId(value, what) {
+    if (typeof value === "string") {
+        // Go's `strconv.ParseInt` takes a sign and rejects everything else whole;
+        // there is no prefix parsing and no whitespace trimming.
+        if (!/^[+-]?\d+$/.test(value))
+            return 0;
+        return boundedPersonId(BigInt(value), value, what);
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} id is ${describeWireValue(value)} rather than a person id`), undefined, { retryable: false, hint: RECORDING_HINT });
+    }
+    // A number reaching here has already been through `JSON.parse`, so anything
+    // past 2^53 was rounded before this port could see it and the exactness this
+    // guard asks for was lost upstream. The WINDOW is still checkable and still
+    // the reference's, which is what this enforces.
+    return boundedPersonId(BigInt(value), value, what);
+}
+/** The int64 window and this runtime's exactness limit, for a person id. */
+function boundedPersonId(parsed, raw, what) {
+    if (parsed > INT64_MAX || parsed < INT64_MIN) {
+        throw Errors.apiError(truncateErrorMessage(`${what} id overflows int64 (${describeIdValue(raw)})`), undefined, { retryable: false, hint: RECORDING_HINT });
+    }
+    const id = Number(parsed);
+    if (!Number.isSafeInteger(id)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} id cannot be represented exactly by this runtime (${describeIdValue(raw)})`), undefined, { retryable: false, hint: RECORDING_HINT });
+    }
+    return id;
+}
+/**
+ * A nested identity, typed as the reference types it, or `undefined` for Go's
+ * zero value.
+ *
+ * This used to check only that the slot held an OBJECT and then carry the
+ * member verbatim, under a doc comment claiming "a shape Go's decoder refuses
+ * fails the read here too" — which was true of the container and false of every
+ * field inside it, so `{"creator":{"name":7}}` produced a summary whose `name`
+ * was a number in a field the contract declares a string. Card 39 settled the
+ * cross-port fork in favour of the reference's line: four of the seven SDKs
+ * reproduce the whole nested decode for free through a typed decoder and cannot
+ * stop short of it, so a port that stopped at the container was the outlier.
+ *
+ * "Typed as the reference types it" is meant literally and is held to it by
+ * `conformance/tests/recording_summary.json`. What falls short is enumerated in
+ * full in SPEC's TypeScript row rather than here, because every partial copy of
+ * that list in this file has drifted from it. Of the eight named there, SEVEN
+ * pass through this function — all but `normalizePersonIds`, which rewrites the
+ * body before any composite sees it:
+ *
+ *   - the three `flexiblePersonId` names: a `7.0` this runtime cannot see, a
+ *     person's `created_at` / `updated_at` checked for type and not parsed, and
+ *     an id past 2^53 it cannot hold;
+ *   - `9223372036854775807` as a parent or bucket id, which `wireInteger` in the
+ *     two arms below refuses for the same parse reason;
+ *   - an assignee's null `name`, which the person arm passes through where Go
+ *     emits `""` (see `withEmptyLabel`);
+ *   - the EMPTINESS rule, on a different axis. Go builds a nested member only
+ *     when `Id != 0 || Name != ""`, so an all-zero member leaves the key out
+ *     there and Ruby drops it too, while this port emits `{}`. That is the
+ *     projection's shape rather than its typing, and it predates this rule;
+ *   - and the parent's nested bucket, below.
+ *
+ * The first version of this comment claimed a completeness it did not have,
+ * which is the failure mode this whole card exists to correct.
+ *
+ * The parent's nested bucket, on the EMISSION side and shared with Ruby: a parent's nested `bucket` is
+ * typed here — a wrong-typed one fails the read, as the generated decode does —
+ * and then passed through whole with its id undecoded, while the reference's
+ * conversion builds a `Parent` without a bucket and emits no such key at all.
+ * The recursive call below is for its refusals only, and says so.
+ */
+function nestedIdentity(value, what, kind, parentHasBucket = true) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw Errors.apiError(truncateErrorMessage(`${what} is ${describeWireValue(value)} rather than an object`), undefined, { retryable: false, hint: "the response is malformed; the recording cannot be summarized from it" });
+    }
+    const member = value;
+    switch (kind) {
+        case "person": {
+            for (const field of PERSON_STRING_FIELDS)
+                memberString(member, field, what);
+            for (const field of PERSON_BOOL_FIELDS)
+                memberBool(member, field, what);
+            memberCompany(member, what);
+            // Absent is the zero value and is NOT invented — the reference emits a
+            // whole struct and this tier emits the object it was given, so writing an
+            // id in would be half a decode in the other direction.
+            if (!("id" in member))
+                return value;
+            const id = flexiblePersonId(member["id"], what);
+            if (id === member["id"])
+                return value;
+            // Copied rather than mutated: the caller's response object is not ours.
+            return { ...member, id };
+        }
+        case "parent": {
+            for (const field of PARENT_STRING_FIELDS)
+                memberString(member, field, what);
+            // A parent's `Id` is a PLAIN `int64` — not the `FlexibleInt64` a person's
+            // is, so `"7"` fails the read here and resolves one member over. This was
+            // missing while the doc above claimed the member was typed as the
+            // reference types it, which is the one kind of comment this file's own
+            // history says to distrust.
+            const parentId = wireInteger(member["id"], what, RECORDING_HINT);
+            // A parent's bucket is a typed `*RecordingBucket` under
+            // `RecordingParent` and does not exist AT ALL under `TodoParent`, which
+            // is what a todo and a todolist carry. The same key is a typed struct
+            // under one containing type and an ignored unknown under another, and
+            // only the reference says which — hence the flag, threaded from the
+            // routing arm rather than guessed from the payload. One shape for both
+            // would refuse `{"parent":{"bucket":7}}` on a todo, a body the reference
+            // ACCEPTS, which is the direction that matters.
+            // For its REFUSALS only — the return value is discarded, so the nested
+            // bucket is emitted as it arrived. See the emission residue above.
+            if (parentHasBucket)
+                nestedIdentity(member["bucket"], `${what} bucket`, "bucket");
+            return withDecodedId(member, parentId, value);
+        }
+        case "bucket": {
+            for (const field of BUCKET_STRING_FIELDS)
+                memberString(member, field, what);
+            // `RecordingBucket` and `TodoBucket` are `{id int64, name string, type
+            // string}` — THREE fields, and this arm walked two of them. The
+            // top-level bucket's id is read again by the cross-project check below,
+            // which is why the gap was invisible there; a PARENT's bucket has no such
+            // second reader, so `{"parent":{"bucket":{"id":"7"}}}` projected a
+            // summary where the reference fails the read.
+            return withDecodedId(member, wireInteger(member["id"], what, RECORDING_HINT), value);
+        }
+    }
+}
+/**
+ * The member with its DECODED id, for the two members whose id is a plain
+ * `int64`.
+ *
+ * Reading an id one way and emitting it another is the defect this file has
+ * already fixed twice, one member over: a `null` id is the zero value in Go and
+ * reaches a caller as `0` there and in Ruby, while passing the member through
+ * verbatim left it as `null` — a shape no other SDK produces, in a field typed
+ * `number`. An ABSENT id is still not invented; only a present one is written
+ * back.
+ */
+function withDecodedId(member, id, value) {
+    if (!("id" in member) || member["id"] === id)
+        return value;
+    return { ...member, id };
+}
+/**
+ * The member with a present-but-null LABEL written back as `""`.
+ *
+ * The label is the one string field the reference's emptiness rule reads —
+ * `Name` for a bucket and a creator, `Title` for a parent — and all three are
+ * `string` in the generated model, so a JSON null is the zero value and Go
+ * emits `""`. Ruby writes it back the same way (`#read_member`). This port
+ * passed the member through and emitted `null` in a field typed `string`, the
+ * same read-one-way-emit-another shape `withDecodedId` closes for the id.
+ *
+ * Only these three members, and NOT an assignee — which is a divergence, stated
+ * rather than hidden: Go decodes `[]Person` and emits a null assignee name as
+ * `""` too, while this port and Ruby's `#read_assignees` both pass it through
+ * as null. It is left matching Ruby rather than moved alone, because a port
+ * fixing one member of a shared residue in isolation is how the ports came to
+ * disagree in the first place. An ABSENT label is not invented.
+ */
+function withEmptyLabel(value, label) {
+    if (value === undefined)
+        return undefined;
+    const member = value;
+    if (!(label in member) || member[label] !== null)
+        return value;
+    return { ...member, [label]: "" };
+}
+/**
+ * A string field a routed read carries, refused when it is not one.
+ *
+ * Go's generated models decode these as `string`: a JSON null is the zero value
+ * and no error, and a number, a boolean, an object or an array fails the read.
+ * TypeScript carried whatever arrived into the projection, so `content: 42`
+ * reached `mentionedPersonIds`, whose first string operation threw a raw
+ * TypeError out of `summarize` — the same untyped-throw boundary the body and
+ * container checks close, one level further in.
+ */
+function recordingText(value, what, hint = RECORDING_HINT) {
+    if (value === undefined || value === null)
+        return "";
+    if (typeof value !== "string") {
+        throw Errors.apiError(truncateErrorMessage(`${what} is ${describeWireValue(value)} rather than text`), undefined, { retryable: false, hint });
+    }
+    return value;
+}
+//# sourceMappingURL=recordings-extensions.js.map