@chatpanel/events 0.50.0 → 0.53.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.50.0",
+  "version": "0.53.0",
   "description": "The canonical ChatPanel event-log and capability contracts — typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./adapters.js": "./adapters.js",
+    "./attribution.js": "./attribution.js",
     "./backup-envelope.js": "./backup-envelope.js",
     "./capability.js": "./capability.js",
     "./citations.js": "./citations.js",

package/schedule.js

@@ -112,6 +112,51 @@ export function nextFireAt(schedule, from) {
   }
 }
 
+/** Sunday-first, matching `Date#getDay()` and the `weekday` field. */
+export const WEEKDAY_NAMES = Object.freeze([
+  'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday',
+]);
+
+const hhmm = (s) => `${String(s?.hour ?? 0).padStart(2, '0')}:${String(s?.minute ?? 0).padStart(2, '0')}`;
+
+/**
+ * A schedule as a sentence: "every weekday at 08:00", not `{kind:'daily',hour:8,...}`.
+ *
+ * It lives beside the model rather than in a client because a schedule the user cannot read
+ * back is a schedule they cannot trust, and every client has to solve that. The desktop and
+ * the extension had already written this twice, and the copies disagreed: one rendered
+ * `weekdaysOnly` and the other silently dropped it, so a job that skipped weekends still
+ * read as "every day".
+ *
+ * Returns '' for a schedule it cannot describe rather than inventing one — an unreadable
+ * label is better than a confident wrong one.
+ */
+export function describeSchedule(s) {
+  if (!s || typeof s !== 'object') return '';
+  switch (s.kind) {
+    case 'once': {
+      if (!(s.at > 0)) return '';
+      return `once, at ${new Date(s.at).toLocaleString()}`;
+    }
+    case 'interval': {
+      const ms = Number(s.everyMs) || 0;
+      if (ms < 60_000) return '';
+      const mins = Math.round(ms / 60_000);
+      if (mins % 1440 === 0) { const d = mins / 1440; return `every ${d === 1 ? 'day' : `${d} days`}`; }
+      if (mins % 60 === 0) { const h = mins / 60; return `every ${h === 1 ? 'hour' : `${h} hours`}`; }
+      return `every ${mins} minutes`;
+    }
+    case 'daily':
+      return s.weekdaysOnly ? `every weekday at ${hhmm(s)}` : `every day at ${hhmm(s)}`;
+    case 'weekly': {
+      const name = WEEKDAY_NAMES[s.weekday];
+      return name ? `every ${name} at ${hhmm(s)}` : '';
+    }
+    default:
+      return '';
+  }
+}
+
 /** Every firing in (from, to], oldest first. Capped: a long sleep is not a queue of work. */
 export function occurrencesBetween(schedule, from, to, max = MAX_CATCH_UP) {
   const out = [];

package/sync-plan.js

@@ -64,6 +64,25 @@ function indexById(entries) {
  *   'push'     — local is newer, or remote has never seen it; send ours
  *   'conflict' — both changed since the last common state and neither is clearly newer
  */
+/**
+ * Is this entry the COMPLETE record, or a flattened stand-in for one?
+ *
+ * A warm/indexed copy of a chat is its transcript as one blob of text: enough to search,
+ * read and cite, and not enough to open as a conversation. Callers stamp that with
+ * `meta.lossy` (or `meta.origin: 'warm'`); a stamp row may carry `lossy` directly, because a
+ * sync plan works on stamps and should not have to load bodies to make this decision.
+ *
+ * Returns 1 for full fidelity and 0 for lossy — an ordering, so the rule below is a
+ * comparison rather than a pile of branches.
+ */
+export function fidelityOf(entry) {
+  if (!entry) return 0;
+  if (entry.lossy === true) return 0;
+  const meta = entry.meta || null;
+  if (meta && (meta.lossy === true || meta.origin === 'warm')) return 0;
+  return 1;
+}
+
 export function decide(local, remote, { tolerance = CLOCK_TOLERANCE_MS, base = null } = {}) {
   if (!local && !remote) return 'none';
   if (!remote) return 'push';
@@ -71,6 +90,30 @@ export function decide(local, remote, { tolerance = CLOCK_TOLERANCE_MS, base = n
 
   const l = stampOf(local);
   const r = stampOf(remote);
+
+  // FIDELITY BEATS RECENCY, BOTH WAYS.
+  //
+  // The two sides are not always describing the same kind of thing. One may hold the whole
+  // record and the other a flattened stand-in for it — and those two arrive with the SAME
+  // timestamp, because they describe the same moment. Last-write-wins then reads them as
+  // equal and answers 'none', which is how a complete conversation restored from a backup
+  // gets silently refused in favour of a search-index summary of itself that is already
+  // there. The user restores, is told it worked, and still sees the flattened copy.
+  //
+  // So a complete record always wins over a partial one whatever the clocks say. The
+  // converse — never let a partial overwrite a complete one — is the same rule read the
+  // other way, and it is the one callers usually remember to enforce by hand.
+  //
+  // DELETIONS ARE EXEMPT. A tombstone carries no body, so it is 'lossy' by any measure, and
+  // resurrecting deleted records because their replacement looks fuller would be a far worse
+  // bug than the one this fixes. When either side is deleted, the stamps decide.
+  const deleted = num(local.deletedAt) > 0 || num(remote.deletedAt) > 0;
+  if (!deleted) {
+    const lf = fidelityOf(local);
+    const rf = fidelityOf(remote);
+    if (lf !== rf) return rf > lf ? 'pull' : 'push';
+  }
+
   const delta = l - r;
   if (Math.abs(delta) <= tolerance) return 'none';