borgmcp-shared 0.2.2

package/src/conformance/index.ts

@@ -0,0 +1,68 @@
+import type { BroadcastHwm } from '../log-stream-hwm.js';
+
+export * from './adapter.js';
+
+/** A portable input/output vector that can be consumed by any test runner. */
+export interface ConformanceVector<Input, Output> {
+  name: string;
+  input: Input;
+  expected: Output;
+}
+
+export interface BroadcastHwmComparisonInput {
+  a: BroadcastHwm;
+  b: BroadcastHwm;
+}
+
+export const BROADCAST_HWM_CONFORMANCE: readonly ConformanceVector<
+  BroadcastHwmComparisonInput,
+  -1 | 0 | 1
+>[] = [
+  {
+    name: 'orders by timestamp',
+    input: {
+      a: { id: 'z', created_at: '2026-05-29T09:59:59.000Z' },
+      b: { id: 'a', created_at: '2026-05-29T10:00:00.000Z' },
+    },
+    expected: -1,
+  },
+  {
+    name: 'breaks equal-timestamp ties by id',
+    input: {
+      a: { id: 'a', created_at: '2026-05-29T10:00:00.000Z' },
+      b: { id: 'b', created_at: '2026-05-29T10:00:00.000Z' },
+    },
+    expected: -1,
+  },
+  {
+    name: 'compares identical tuples as equal',
+    input: {
+      a: { id: 'a', created_at: '2026-05-29T10:00:00.000Z' },
+      b: { id: 'a', created_at: '2026-05-29T10:00:00.000Z' },
+    },
+    expected: 0,
+  },
+  {
+    name: 'falls back to raw timestamp ordering for invalid dates',
+    input: {
+      a: { id: 'a', created_at: 'not-a-date-a' },
+      b: { id: 'a', created_at: 'not-a-date-b' },
+    },
+    expected: -1,
+  },
+];
+
+export const DRONE_ADDRESS_CONFORMANCE: readonly ConformanceVector<string, string>[] = [
+  {
+    name: 'formats the stable lowercase eight-character id prefix',
+    input: '3336CDE1-a76e-4e89-8bc2-77c149bb6a74',
+    expected: '`id:3336cde1`',
+  },
+];
+
+export const ROLE_SECTION_ROUND_TRIP_CONFORMANCE: readonly string[] = [
+  '',
+  'Preamble only.',
+  'Preamble.\n\nWorkflow:\n- step one\n\nProject conventions:\n- TDD.\n',
+  '**Markdown heading:**\nMust remain part of the preamble.\n',
+];

package/src/domain/index.ts

@@ -0,0 +1,9 @@
+export * from '../drone-address.js';
+export * from '../log-stream-hwm.js';
+export * from '../role-section.js';
+export type {
+  MessageTaxonomy,
+  MessageTaxonomyClass,
+  Template,
+  TemplateRole,
+} from '../templates.js';

package/src/drone-address.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared short-UUID rendering keeps roster and activity-log addresses
+ * consistent. A drone label may change as cube membership changes; the ID
+ * prefix remains the stable address.
+ */
+
+/**
+ * The stable short-uuid: the first 8 hex of the drone_id (UUID). It is, by
+ * construction, a valid `startsWith` prefix of the full drone ID. It is
+ * lowercased so case differences cannot create cross-surface drift.
+ */
+export function shortDroneId(droneId: string): string {
+  return droneId.slice(0, 8).toLowerCase();
+}
+
+/**
+ * The clearly-LABELED address token shown beside a drone on the roster and on
+ * each read-log entry: `` `id:3336cde1` ``. Backticked so it
+ * renders monospace — visually distinct from the plain `[entry_id: …]` bracket
+ * that sits beside it in read-log, so a weak model never confuses which token
+ * to `borg_ack` with (entry_id) versus address a dispatch to (`id:` short-uuid).
+ */
+export function formatDroneAddressToken(droneId: string): string {
+  return `\`id:${shortDroneId(droneId)}\``;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './protocol/index.js';
+export * from './domain/index.js';
+export * from './conformance/index.js';
+export * from './templates.js';

package/src/log-stream-hwm.ts

@@ -0,0 +1,16 @@
+export interface BroadcastHwm {
+  id: string;
+  created_at: string;
+}
+
+export function compareBroadcastHwm(a: BroadcastHwm, b: BroadcastHwm): number {
+  const aTime = Date.parse(a.created_at);
+  const bTime = Date.parse(b.created_at);
+  if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) {
+    return aTime - bTime;
+  }
+  if (a.created_at !== b.created_at) {
+    return a.created_at < b.created_at ? -1 : 1;
+  }
+  return a.id.localeCompare(b.id);
+}