Caps That Only a Person Resets

/**
* The sentence a sender reads when its message was too long.
*
* @param {number} length
* @param {number} limit
* @returns {string}
*/
export function tooLongText(length, limit) {
return [
  `Refused: that message is ${length} characters and the limit is ${limit}.`,
  "Nothing was delivered and nothing was counted against your budget.",
  "Send a shorter one; a summary is what the recipient can act on anyway.",
].join(" ");
}

/**
* The sentence a sender reads when the connection's ceiling is spent.
*
* Three facts, in the order a model needs them: the number, the fact that time
* will not help, and who can help. The last clause is the one that separates
* this from the rate limit's refusal, a model that reads them as the same kind
* of answer will retry, and retrying is the behaviour the ceiling exists to
* stop.
*
* @param {number} used
* @param {number} ceiling
* @returns {string}
*/
export function ceilingSpentText(used, ceiling) {
return [
  `Refused: this connection's ceiling of ${ceiling} agent-to-agent messages is spent`,
  `(${used} of ${ceiling} used).`,
  "The ceiling does not decay. Waiting will not clear it and neither will",
  "trying again; only a person opening a new connection resets the count.",
  "Nothing was delivered. Do not attempt another send this session:",
  "say what you needed to say in your own answer instead.",
].join(" ");
}

/**
* The sentence a sender reads when a recipient is receiving too fast.
*
* The opposite advice to the ceiling's, and deliberately worded so the two
* cannot be confused. This one says room opens, and roughly when. A model that
* reads "in about 40 seconds" and carries on with its own work is doing the
* right thing; so is one that decides not to bother.
*
* "About" and whole seconds, because the honest resolution here is a shrug. The
* window is rolling, so the exact instant depends on a timestamp the model
* cannot see, and a number to the millisecond would be false precision about a
* thing that is already approximate by the time it is read.
*
* @param {AgentRecord} to
* @param {number} perMinute
* @param {number} inSeconds
* @returns {string}
*/
export function rateLimitedText(to, perMinute, inSeconds) {
return [
  `Refused: ${to.name} (${to.agentId}) has already received ${perMinute}`,
  `message${perMinute === 1 ? "" : "s"} in the last minute, which is this`,
  `connection's limit of ${perMinute} per recipient per minute.`,
  `Room opens in about ${inSeconds} second${inSeconds === 1 ? "" : "s"}.`,
  "Nothing was delivered and nothing was counted against your ceiling.",
  "Carry on with your own work; send again later only if it still matters.",
].join(" ");
}

// ... the class's fields, its constructor, and the rolling-minute window it
// keeps per recipient. Unabridged in the repository at this tag.

/**
 * Decide whether one delivery may happen, and count it if it may.
 *
 * Three checks, in this order, and the order is an argument rather than an
 * accident. Record 0086 makes it in full; the short version is that the
 * length cap is the only one of the three that reads no state and can be
 * decided from the message alone, so it goes first, and between the two gates
 * the ceiling goes first because it is the one whose answer is final. A
 * message refused by a rate limit is worth sending again later; there is no
 * later once the ceiling is spent, and telling a model to wait for room that
 * will never open would be the worst of the three answers.
 *
 * On refusal nothing is counted. A refused message did not reach a queue, and
 * a ceiling that counted attempts would let a sender spend its whole budget on
 * messages nobody ever read.
 *
 * @param {AgentRecord} to The recipient's record, so the refusal can name it.
 * @param {string} text What the sender wrote, unprefixed.
 * @returns {{ ok: true, used: number, ceiling: number, remaining: number,
 *     warn: boolean }
 *   | { ok: false, gate: "length" | "ceiling" | "rate", message: string,
 *     used: number, ceiling: number, remaining: number }}
 */
admit(to, text) {
  const at = this.#now();

  if (text.length > this.#maxChars) {
    return {
      ok: false,
      gate: "length",
      message: tooLongText(text.length, this.#maxChars),
      used: this.#used,
      ceiling: this.#ceiling,
      remaining: this.remaining,
    };
  }

  if (this.#used >= this.#ceiling) {
    return {
      ok: false,
      gate: "ceiling",
      message: ceilingSpentText(this.#used, this.#ceiling),
      used: this.#used,
      ceiling: this.#ceiling,
      remaining: 0,
    };
  }

  const window = this.#window(to.agentId, at);
  if (window.length >= this.#perMinute) {
    // The oldest live timestamp is the one that will fall out first, so its
    // age is what a sender is waiting on. Rounded up, and never reported as
    // zero: "room opens in about 0 seconds" reads as a bug.
    const waitMs = window[0] + WINDOW_MS - at;
    const inSeconds = Math.max(1, Math.ceil(waitMs / 1000));
    return {
      ok: false,
      gate: "rate",
      message: rateLimitedText(to, this.#perMinute, inSeconds),
      used: this.#used,
      ceiling: this.#ceiling,
      remaining: this.remaining,
    };
  }

  // Past every gate. Both counters move here and nowhere else.
  this.#used += 1;
  window.push(at);
  this.#recent.set(to.agentId, window);

  const remaining = this.remaining;
  return {
    ok: true,
    used: this.#used,
    ceiling: this.#ceiling,
    remaining,
    warn: remaining <= warnThreshold(this.#ceiling),
  };
}
}