@zhin.js/harness 0.0.0-stage → 0.0.0

package/src/policies/groups.ts

@@ -0,0 +1,137 @@
+/**
+ * Turn groups of a lane's queue (ADR 0048 H3; semantics of the former
+ * `TurnAdmissionGate`, ADR 0038 §1/§5 and #725).
+ *
+ * The queue holds single mails; a group is the set of queued mails one turn
+ * will answer. Groups are recomputed from the queue on every decision, so
+ * the policy stays pure. Replaying the queue in order:
+ *
+ * - **live** (danmaku, when enabled): joins the lane's last live group, no
+ *   sender limit.
+ * - **merge** (mergeable plain text, when a merge window is enabled): joins
+ *   the last merge group that already has the sender (burst), else the last
+ *   merge group with fewer than `maxSenders` senders, else opens a new one.
+ * - **single** (everything else): joins the sender's own queued group when
+ *   that is a single plain-text group and this mail is plain text too
+ *   (burst coalescing); otherwise opens a new group. A member never joins
+ *   another member's single group.
+ * - Mails requeued by a stale discard (`carriedInto`) belong to the group of
+ *   their target mail, ahead of it, regardless of `maxSenders`; when the
+ *   target left the queue they form their own group.
+ *
+ * Groups are ordered by their first mail in the queue; the head group always
+ * contains the queue's first mail.
+ */
+import type { InboxEntry, Mail, MailId } from '../contracts.js';
+import { inboxMarkers } from './markers.js';
+
+export type InboxGroupKind = 'single' | 'merge' | 'live';
+
+export interface InboxGroup {
+  readonly kind: InboxGroupKind;
+  /** In queue order. */
+  readonly entries: readonly InboxEntry[];
+  /** Distinct senders in queue order. */
+  readonly senders: readonly string[];
+  readonly plainText: boolean;
+  /** Earliest / latest (re)queue time of the group's own (not carried) mails. */
+  readonly openedAt: number;
+  readonly lastJoinedAt: number;
+}
+
+export interface InboxGroupingOptions {
+  /** Merge windows enabled; omitted = mergeable is ignored. */
+  readonly merge?: { readonly maxSenders: number };
+  /** Danmaku windows enabled. */
+  readonly live?: boolean;
+}
+
+export function classifyMail(mail: Mail, options: InboxGroupingOptions): InboxGroupKind {
+  const m = inboxMarkers(mail);
+  if (options.live && m.live) return 'live';
+  if (options.merge && m.mergeable && m.plainText) return 'merge';
+  return 'single';
+}
+
+interface Draft {
+  readonly kind: InboxGroupKind;
+  readonly own: Set<string>;
+  plainText: boolean;
+}
+
+export function groupInbox(entries: readonly InboxEntry[], options: InboxGroupingOptions): InboxGroup[] {
+  const maxSenders = Math.max(1, Math.floor(options.merge?.maxSenders ?? 1));
+  const drafts: Draft[] = [];
+  const draftOf = new Map<InboxEntry, Draft>();
+  const byMail = new Map<MailId, Draft>();
+  const findLast = (predicate: (d: Draft) => boolean): Draft | undefined => {
+    for (let i = drafts.length - 1; i >= 0; i -= 1) if (predicate(drafts[i]!)) return drafts[i];
+    return undefined;
+  };
+  const open = (kind: InboxGroupKind, plainText: boolean): Draft => {
+    const d: Draft = { kind, own: new Set(), plainText };
+    drafts.push(d);
+    return d;
+  };
+
+  for (const entry of entries) {
+    if (entry.carriedInto !== undefined) continue;
+    const m = inboxMarkers(entry.mail);
+    const kind = classifyMail(entry.mail, options);
+    let d: Draft;
+    if (kind === 'live') {
+      d = findLast((g) => g.kind === 'live') ?? open('live', true);
+    } else if (kind === 'merge') {
+      d = findLast((g) => g.kind === 'merge' && g.own.has(m.senderId))
+        ?? findLast((g) => g.kind === 'merge' && g.own.size < maxSenders)
+        ?? open('merge', true);
+    } else {
+      const own = findLast((g) => g.own.has(m.senderId));
+      d = own && own.kind === 'single' && own.plainText && m.plainText ? own : open('single', m.plainText);
+    }
+    d.own.add(m.senderId);
+    draftOf.set(entry, d);
+    byMail.set(entry.mail.id, d);
+  }
+  for (const entry of entries) {
+    if (entry.carriedInto === undefined) continue;
+    const target = byMail.get(entry.carriedInto);
+    if (target) {
+      draftOf.set(entry, target);
+    } else {
+      const d: Draft = { kind: 'single', own: new Set([inboxMarkers(entry.mail).senderId]), plainText: inboxMarkers(entry.mail).plainText };
+      draftOf.set(entry, d);
+    }
+  }
+
+  const order: Draft[] = [];
+  const members = new Map<Draft, InboxEntry[]>();
+  for (const entry of entries) {
+    const d = draftOf.get(entry)!;
+    let list = members.get(d);
+    if (!list) {
+      list = [];
+      members.set(d, list);
+      order.push(d);
+    }
+    list.push(entry);
+  }
+  return order.map((d) => {
+    const list = members.get(d)!;
+    const own = list.filter((e) => e.carriedInto === undefined);
+    const times = (own.length > 0 ? own : list).map((e) => e.postedAt);
+    const senders: string[] = [];
+    for (const e of list) {
+      const s = inboxMarkers(e.mail).senderId;
+      if (!senders.includes(s)) senders.push(s);
+    }
+    return Object.freeze({
+      kind: d.kind,
+      entries: Object.freeze(list),
+      senders: Object.freeze(senders),
+      plainText: d.plainText,
+      openedAt: Math.min(...times),
+      lastJoinedAt: Math.max(...times),
+    });
+  });
+}

package/src/policies/index.ts

@@ -0,0 +1,5 @@
+export * from './markers.js';
+export * from './groups.js';
+export * from './merge.js';
+export * from './live.js';
+export * from './admission.js';

package/src/policies/live.ts

@@ -0,0 +1,68 @@
+/**
+ * Danmaku window (ADR 0038 §5) as an inbox policy part.
+ *
+ * Every danmaku of a lane waits in one window that closes `windowMs` after
+ * its first mail, but never sooner than `minIntervalMs` after the lane's
+ * previous danmaku turn ended. No sender limit; the window keeps the newest
+ * `LIVE_WINDOW_MAX_MESSAGES` mails (older ones are evicted, counted in
+ * `InboxTurnFacts.evicted`), and one turn answers it.
+ */
+import type { InboxEntry, MailId } from '../contracts.js';
+import type { InboxGroup } from './groups.js';
+import { inboxMarkers } from './markers.js';
+
+export interface LiveWindowOptions {
+  /** Answer the window this long after its first danmaku. */
+  readonly windowMs: number;
+  /** Never start a danmaku turn sooner than this after the lane's previous one ended. */
+  readonly minIntervalMs: number;
+}
+
+/** Danmaku one window keeps for the model; older ones are evicted. */
+export const LIVE_WINDOW_MAX_MESSAGES = 100;
+
+export function normalizeLiveWindow(options: LiveWindowOptions): LiveWindowOptions {
+  return Object.freeze({
+    windowMs: Math.max(0, options.windowMs),
+    minIntervalMs: Math.max(0, options.minIntervalMs),
+  });
+}
+
+/** When a live group may be answered; `lastLiveEndedAt` = end of the lane's previous danmaku turn. */
+export function liveWindowDueAt(
+  group: Pick<InboxGroup, 'openedAt'>,
+  lastLiveEndedAt: number | undefined,
+  options: LiveWindowOptions,
+): number {
+  return Math.max(group.openedAt + options.windowMs, lastLiveEndedAt === undefined ? 0 : lastLiveEndedAt + options.minIntervalMs);
+}
+
+/**
+ * Mails to evict so a live group keeps at most `max` mails: the earliest
+ * sender's oldest mail goes first (as the former gate did), so memory stays
+ * bounded however busy the room is.
+ */
+export function liveEvictions(entries: readonly InboxEntry[], max: number = LIVE_WINDOW_MAX_MESSAGES): readonly MailId[] {
+  const excess = entries.length - Math.max(0, max);
+  if (excess <= 0) return [];
+  const order: string[] = [];
+  const by = new Map<string, MailId[]>();
+  for (const e of entries) {
+    const s = inboxMarkers(e.mail).senderId;
+    let list = by.get(s);
+    if (!list) {
+      list = [];
+      by.set(s, list);
+      order.push(s);
+    }
+    list.push(e.mail.id);
+  }
+  const out: MailId[] = [];
+  for (const s of order) {
+    for (const id of by.get(s)!) {
+      if (out.length >= excess) return out;
+      out.push(id);
+    }
+  }
+  return out;
+}

package/src/policies/markers.ts

@@ -0,0 +1,58 @@
+/**
+ * Reads the inbox-policy markers of a mail (ADR 0048 H3).
+ *
+ * Only `human` mail carries markers (`MailBody.human`). Every other kind is
+ * an ordinary, non-plain, non-mergeable mail from its transport sender, so
+ * actor / timer / event mail is never merged into, superseded by, or used to
+ * stop a human's turn.
+ */
+import { senderOf, type Mail } from '../contracts.js';
+
+export interface InboxMarkers {
+  readonly senderId: string;
+  readonly senderName?: string;
+  readonly text: string;
+  readonly messageId?: string;
+  readonly human: boolean;
+  readonly plainText: boolean;
+  readonly mergeable: boolean;
+  readonly live: boolean;
+  readonly isMaster: boolean;
+  readonly isStop: boolean;
+  readonly unaddressed: boolean;
+}
+
+function textOf(mail: Mail): string {
+  const body = mail.body;
+  switch (body.kind) {
+    case 'human': return body.text;
+    case 'ask': return body.question;
+    case 'delegate': return body.brief;
+    case 'tell': return body.content;
+    case 'result': return body.content;
+    case 'timer': return body.content;
+    default: return '';
+  }
+}
+
+export function inboxMarkers(mail: Mail): InboxMarkers {
+  const senderId = senderOf(mail);
+  const text = textOf(mail);
+  const body = mail.body;
+  if (body.kind !== 'human') {
+    return { senderId, text, human: false, plainText: false, mergeable: false, live: false, isMaster: false, isStop: false, unaddressed: false };
+  }
+  return {
+    senderId,
+    ...(body.senderName ? { senderName: body.senderName } : {}),
+    text,
+    ...(body.messageId ? { messageId: body.messageId } : {}),
+    human: true,
+    plainText: body.plainText === true,
+    mergeable: body.mergeable === true,
+    live: body.live === true,
+    isMaster: body.isMaster === true,
+    isStop: body.isStop === true,
+    unaddressed: body.unaddressed === true,
+  };
+}

package/src/policies/merge.ts

@@ -0,0 +1,121 @@
+/**
+ * Merge window (ADR 0038 §1) as an inbox policy part, plus the helpers a
+ * merged turn needs (ADR 0048 H3, Q2).
+ *
+ * A merge group is answered once it went quiet for `quietMs` or, at the
+ * latest, `maxWaitMs` after it opened. Q2 (accepted): a merged batch runs in
+ * its first mail's engagement; its principal is the first human sender; its
+ * authority is the intersection of every sender's authority. These helpers
+ * are exposed now; wiring them into the IM turn is PR-2.
+ */
+import { intersectScopes, type Authority, type Mail, type Principal } from '../contracts.js';
+import { minTrust } from '../authority.js';
+import type { InboxGroup } from './groups.js';
+import { inboxMarkers } from './markers.js';
+
+export interface MergeWindowOptions {
+  /** Flush once no new mail joined the window for this long. */
+  readonly quietMs: number;
+  /** Flush at the latest this long after the window opened. */
+  readonly maxWaitMs: number;
+  /** Senders one window may hold; further senders open the next window. */
+  readonly maxSenders: number;
+}
+
+export function normalizeMergeWindow(options: MergeWindowOptions): MergeWindowOptions {
+  return Object.freeze({
+    quietMs: Math.max(0, options.quietMs),
+    maxWaitMs: Math.max(0, options.maxWaitMs),
+    maxSenders: Math.max(1, Math.floor(options.maxSenders)),
+  });
+}
+
+/** When a merge group may be answered. */
+export function mergeWindowDueAt(group: Pick<InboxGroup, 'openedAt' | 'lastJoinedAt'>, options: MergeWindowOptions): number {
+  return Math.min(group.lastJoinedAt + options.quietMs, group.openedAt + options.maxWaitMs);
+}
+
+/** One sender's mails in a batch, in arrival order. */
+export interface InboxParticipant {
+  readonly senderId: string;
+  readonly senderName?: string;
+  readonly texts: readonly string[];
+  /** Platform message ids behind `texts`, when known. */
+  readonly messageIds?: readonly string[];
+  readonly mails: readonly Mail[];
+}
+
+/** Groups a batch by sender, senders in order of their first mail. */
+export function participantsOf(batch: readonly Mail[]): readonly InboxParticipant[] {
+  const order: string[] = [];
+  const by = new Map<string, { senderName?: string; texts: string[]; messageIds: string[]; mails: Mail[] }>();
+  for (const mail of batch) {
+    const m = inboxMarkers(mail);
+    let p = by.get(m.senderId);
+    if (!p) {
+      p = { ...(m.senderName ? { senderName: m.senderName } : {}), texts: [], messageIds: [], mails: [] };
+      by.set(m.senderId, p);
+      order.push(m.senderId);
+    }
+    if (!p.senderName && m.senderName) p.senderName = m.senderName;
+    p.texts.push(m.text);
+    if (m.messageId) p.messageIds.push(m.messageId);
+    p.mails.push(mail);
+  }
+  return Object.freeze(order.map((senderId) => {
+    const p = by.get(senderId)!;
+    return Object.freeze({
+      senderId,
+      ...(p.senderName ? { senderName: p.senderName } : {}),
+      texts: Object.freeze(p.texts),
+      ...(p.messageIds.length > 0 ? { messageIds: Object.freeze(p.messageIds) } : {}),
+      mails: Object.freeze(p.mails),
+    });
+  }));
+}
+
+/**
+ * One sender: their texts joined by newlines. Several senders: one
+ * `name: text` line per sender so the model can tell who asked what.
+ */
+export function renderInboxText(participants: readonly InboxParticipant[]): string {
+  const lines = (p: InboxParticipant) => p.texts.filter((text) => text.trim());
+  if (participants.length === 1) return lines(participants[0]!).join('\n');
+  return participants
+    .map((p) => ({ name: p.senderName?.trim() || p.senderId, texts: lines(p) }))
+    .filter((p) => p.texts.length > 0)
+    .map((p) => `${p.name}: ${p.texts.join('\n')}`)
+    .join('\n');
+}
+
+/** Q2: the principal of a merged batch is its first human sender. */
+export function firstHumanPrincipal(batch: readonly Mail[]): Principal | undefined {
+  for (const mail of batch) if (mail.from.kind === 'human') return mail.from.principal;
+  return undefined;
+}
+
+/**
+ * Q2: the authority of a merged batch is the intersection of its mails'
+ * authorities (trust = lowest, tools / contacts / egress hosts = common,
+ * network only when everyone has it). Principal, approvers and chain stay
+ * those of the first human mail (approvals go to that principal), so the
+ * result never exceeds any sender's authority.
+ */
+export function mergedAuthority(batch: readonly Mail[]): Authority | undefined {
+  if (batch.length === 0) return undefined;
+  const lead = batch.find((mail) => mail.from.kind === 'human') ?? batch[0]!;
+  const all = batch.map((mail) => mail.authority);
+  const base = lead.authority;
+  return Object.freeze({
+    principal: base.principal,
+    trust: minTrust(...all.map((a) => a.trust)),
+    tools: all.reduce((scope, a) => intersectScopes(scope, a.tools), base.tools),
+    contacts: all.reduce((scope, a) => intersectScopes(scope, a.contacts), base.contacts),
+    egress: Object.freeze({
+      network: all.every((a) => a.egress.network),
+      hosts: all.reduce((scope, a) => intersectScopes(scope, a.egress.hosts), base.egress.hosts),
+    }),
+    approvers: base.approvers,
+    chain: base.chain,
+  });
+}