@moxxy/core 0.26.0 → 0.28.0

package/src/sessions/event-shape.ts

@@ -0,0 +1,196 @@
+/**
+ * Runtime shape guard for event-log lines — the read side of the EventStore
+ * trust boundary.
+ *
+ * The per-session JSONL is parsed back into `MoxxyEvent`s on every resume/
+ * attach (`restoreEvents`), every history page (`readEventPage`), and every
+ * index hydration (`matchingSessionStatsFromLog`). Corrupt-JSON lines were
+ * always skipped, but a structurally-valid-but-wrong-shape line used to be
+ * CAST straight to `MoxxyEvent` and then drive replay and state
+ * reconstruction — e.g. a `compaction` line missing `replacedRange`/`summary`
+ * throws inside `projectMessagesFromLog`'s unconditional
+ * `event.summary.trim()` / `event.replacedRange[0]` dereferences, mid-replay.
+ * This guard closes that gap: wrong-shape lines are skipped with the exact
+ * same semantics as corrupt lines (never throw, never truncate what follows).
+ *
+ * CALIBRATION — why this is a shallow structural check, not a full schema:
+ *
+ * `restoreEvents` REWRITES the repaired log after skipping bad lines, so a
+ * false positive here permanently deletes history. The guard therefore
+ * rejects only shapes that would actively corrupt replay, and tolerates
+ * benign drift:
+ *
+ *  - Envelope: strict on the fields the replay machinery itself dereferences
+ *    (`id`, `seq`, `ts`, `type` — mirrors dedupe by `id`, ingest/paging/
+ *    re-sequencing key on numeric `seq`). Lenient-if-present on `sessionId` /
+ *    `turnId` / `source`: the existing session-ownership path already
+ *    tolerates and normalizes a missing `sessionId`
+ *    (`eventBelongsToSession`), and none of these are dereferenced in a way
+ *    that can throw.
+ *  - Unknown `type` with a valid envelope is KEPT, not dropped: every
+ *    downstream fold pattern-matches known types and ignores the rest (there
+ *    is no exhaustive-switch throw), and the desktop floor mechanism makes
+ *    "older core replaying a newer log" a designed scenario — dropping (and
+ *    then rewriting away) a newer version's events on rollback would be
+ *    silent history loss. This matches the pre-guard behavior for that class
+ *    of line exactly.
+ *  - Known `type`: the variant's required primitive fields are checked
+ *    shallowly (`typeof` / `Array.isArray`), because the projection folds
+ *    dereference them unconditionally. Enum-valued strings (`stopReason`,
+ *    `decidedBy`, …) are checked as `string` only — a newer version adding an
+ *    enum member must not get its events dropped by an older reader.
+ *
+ * LOCKSTEP — the spec map below is typed so it cannot drift from the union:
+ * it is exhaustive over `MoxxyEventType` (adding a variant fails the build
+ * until a spec is added) and each spec's keys must be required non-envelope
+ * keys of that exact variant (renaming/removing a field fails the build).
+ * Listing a field is optional per-variant, so a future required field can be
+ * deliberately left unchecked for back-compat (old logs won't have it) — omit
+ * with a comment when doing so.
+ *
+ * PERFORMANCE — this runs once per line while iterating whole logs on the
+ * replay hot path. It allocates nothing per call: a handful of `typeof`
+ * checks plus an indexed walk over a per-variant spec array precomputed at
+ * module load. (This is also why it is hand-rolled rather than zod: a parsed
+ * schema library allocates per-line result/issue objects and would
+ * deep-validate bulky payloads — attachments, tool outputs — that replay
+ * never dereferences structurally.)
+ */
+
+import type { EventBase, MoxxyEvent, MoxxyEventOfType, MoxxyEventType } from '@moxxy/sdk';
+
+/** Shallow runtime kinds a required variant field can be checked as. */
+type FieldKind = 'string' | 'number' | 'boolean' | 'array' | 'seqRange';
+
+/**
+ * Keys of `T` that are required AND carry a checkable type. `undefined
+ * extends T[K]` excludes both optional fields and `unknown`-typed ones
+ * (`tool_call_requested.input`, `plugin_event.payload`) — the latter on
+ * purpose: any JSON value is a valid `unknown`, and `JSON.stringify` drops
+ * the key entirely when the value was `undefined` at emit time, so even a
+ * presence check would drop legitimate events.
+ */
+type CheckableKeys<T> = { [K in keyof T]-?: undefined extends T[K] ? never : K }[keyof T];
+
+/**
+ * The checkable fields of one variant: required keys that are NOT part of the
+ * shared envelope (`EventBase` + the discriminant). Keys are optional so a
+ * back-compat omission is possible, but any key listed must exist on the
+ * variant — a rename/removal in the sdk union breaks this file's typecheck.
+ */
+type VariantFieldSpec<T extends MoxxyEventType> = {
+  readonly [K in Exclude<
+    CheckableKeys<MoxxyEventOfType<T>>,
+    keyof EventBase | 'type'
+  >]?: FieldKind;
+};
+
+/** Exhaustive per-variant field specs — one entry per union member. */
+const VARIANT_SPECS: { readonly [T in MoxxyEventType]: VariantFieldSpec<T> } = {
+  user_prompt: { text: 'string' },
+  assistant_chunk: { delta: 'string' },
+  assistant_message: { content: 'string', stopReason: 'string' },
+  reasoning_chunk: { delta: 'string' },
+  reasoning_message: { content: 'string' },
+  tool_call_requested: { callId: 'string', name: 'string' },
+  tool_call_approved: { callId: 'string', decidedBy: 'string', mode: 'string' },
+  tool_call_denied: { callId: 'string', decidedBy: 'string', reason: 'string' },
+  tool_result: { callId: 'string', ok: 'boolean' },
+  skill_invoked: { skillId: 'string', name: 'string', reason: 'string' },
+  skill_created: {
+    skillId: 'string',
+    name: 'string',
+    path: 'string',
+    scope: 'string',
+    originatingPrompt: 'string',
+  },
+  plugin_registered: { pluginId: 'string', name: 'string', version: 'string', kind: 'array' },
+  plugin_unregistered: { pluginId: 'string', name: 'string', reason: 'string' },
+  mode_iteration: { strategy: 'string', iteration: 'number' },
+  compaction: {
+    compactor: 'string',
+    replacedRange: 'seqRange',
+    summary: 'string',
+    tokensSaved: 'number',
+  },
+  elision: {
+    elidedThrough: 'number',
+    stubbedRanges: 'array',
+    elideConversational: 'boolean',
+    conversationalRecallThreshold: 'number',
+    maxRecallBytes: 'number',
+    neverElideTools: 'array',
+    tokensSaved: 'number',
+  },
+  provider_request: { provider: 'string', model: 'string' },
+  provider_response: { provider: 'string', model: 'string' },
+  error: { kind: 'string', message: 'string' },
+  abort: { reason: 'string' },
+  plugin_event: { pluginId: 'string', subtype: 'string' },
+};
+
+/** Specs flattened to `[key, kind]` arrays ONCE at module load, so the per-line
+ *  check walks a plain array by index — no per-call object/iterator work. */
+const SPEC_ENTRIES: ReadonlyMap<string, ReadonlyArray<readonly [string, FieldKind]>> = new Map(
+  Object.entries(VARIANT_SPECS).map(([type, spec]) => [
+    type,
+    Object.entries(spec) as ReadonlyArray<readonly [string, FieldKind]>,
+  ]),
+);
+
+function fieldOk(value: unknown, kind: FieldKind): boolean {
+  switch (kind) {
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      // JSON.parse CAN yield non-finite numbers (`1e999` → Infinity); a
+      // non-finite seq-adjacent number poisons every downstream comparison.
+      return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'array':
+      return Array.isArray(value);
+    case 'seqRange':
+      // `[from, to]` seq bounds, compared against `event.seq` unconditionally
+      // by the projection fold — both must be real numbers.
+      return (
+        Array.isArray(value) &&
+        value.length === 2 &&
+        typeof value[0] === 'number' &&
+        Number.isFinite(value[0]) &&
+        typeof value[1] === 'number' &&
+        Number.isFinite(value[1])
+      );
+  }
+}
+
+/**
+ * True when `value` (a successfully-parsed JSONL line) is structurally safe to
+ * replay as a {@link MoxxyEvent}. See the module doc for what "safe" means —
+ * this is a calibrated floor (reject what corrupts replay, keep benign
+ * drift), not a proof of full conformance: an unknown newer event type with a
+ * valid envelope passes, exactly as it (unvalidated) did before this guard.
+ */
+export function isMoxxyEventShape(value: unknown): value is MoxxyEvent {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const e = value as Record<string, unknown>;
+  // Envelope — strict: replay machinery dereferences these on every event.
+  if (typeof e.type !== 'string') return false;
+  if (typeof e.id !== 'string') return false;
+  if (typeof e.seq !== 'number' || !Number.isFinite(e.seq)) return false;
+  if (typeof e.ts !== 'number' || !Number.isFinite(e.ts)) return false;
+  // Envelope — lenient-if-present: absent on some legacy logs (sessionId is
+  // normalized by `eventForSession`), but a present-with-wrong-type value is
+  // junk, not drift.
+  if (e.sessionId != null && typeof e.sessionId !== 'string') return false;
+  if (e.turnId != null && typeof e.turnId !== 'string') return false;
+  if (e.source != null && typeof e.source !== 'string') return false;
+  const fields = SPEC_ENTRIES.get(e.type);
+  // Unknown (newer) event type with a valid envelope: keep — see module doc.
+  if (!fields) return true;
+  for (let i = 0; i < fields.length; i += 1) {
+    const entry = fields[i]!;
+    if (!fieldOk(e[entry[0]], entry[1])) return false;
+  }
+  return true;
+}

package/src/sessions/persistence.test.ts

@@ -589,6 +589,138 @@ describe('SessionPersistence', () => {
     expect(again.lines).toHaveLength(0);
   });
 
+  it('restore skips valid-JSON wrong-shape lines exactly like corrupt ones and repairs the file', async () => {
+    const dir = await makeTempDir();
+    const id = '01BADSHAPE0000000000000000';
+    const mk = (seq: number, text: string) => ({
+      id: `e${seq}`,
+      seq,
+      ts: seq,
+      sessionId: id,
+      turnId: 't1',
+      source: 'user',
+      type: 'user_prompt',
+      text,
+    });
+    const lines = [
+      JSON.stringify(mk(0, 'zero')),
+      // Valid JSON, not an event at all (no envelope).
+      JSON.stringify({ foo: 'bar' }),
+      JSON.stringify(mk(2, 'two')),
+      // Valid envelope + known type, but missing the required fields the
+      // projection fold dereferences unconditionally (would throw mid-replay
+      // if trusted: `event.summary.trim()`, `event.replacedRange[0]`).
+      JSON.stringify({ id: 'junk', seq: 3, ts: 3, sessionId: id, turnId: 't1', source: 'compactor', type: 'compaction', compactor: 'x' }),
+      // Corrupt JSON still goes down its own (unchanged) path.
+      '{half a line',
+      JSON.stringify(mk(5, 'five')),
+    ];
+    await fs.writeFile(path.join(dir, `${id}.jsonl`), lines.join('\n') + '\n', 'utf8');
+
+    const { logger, lines: logged } = captureLogger();
+    const restored = await restoreEvents(id, dir, logger);
+
+    // Survivors only, re-sequenced to contiguous 0..n-1, order + ids preserved.
+    expect(restored.map((e) => e.id)).toEqual(['e0', 'e2', 'e5']);
+    expect(restored.map((e) => e.seq)).toEqual([0, 1, 2]);
+    expect(restored.map((e) => (e as { text?: string }).text)).toEqual(['zero', 'two', 'five']);
+    // One structured warn, counting shape-junk separately from corrupt JSON.
+    const warn = logged.find((l) => l.level === 'warn');
+    expect(warn?.meta).toMatchObject({ corruptLines: 1, invalidShapeLines: 2, restoredEvents: 3 });
+    // Never throws mid-replay: every survivor ingests into a fresh mirror.
+    const mirror = new EventLog();
+    for (const e of restored) mirror.ingest(e);
+    expect(mirror.length).toBe(3);
+    // The file was repaired on disk, so the next restore is clean.
+    const repaired = (await fs.readFile(path.join(dir, `${id}.jsonl`), 'utf8'))
+      .trim()
+      .split('\n')
+      .map((line) => JSON.parse(line) as { id: string });
+    expect(repaired.map((e) => e.id)).toEqual(['e0', 'e2', 'e5']);
+    const again = captureLogger();
+    await restoreEvents(id, dir, again.logger);
+    expect(again.lines).toHaveLength(0);
+  });
+
+  it('restore leaves a fully-valid log untouched on disk and replays it byte-identically', async () => {
+    const dir = await makeTempDir();
+    const id = '01ALLVALID0000000000000000';
+    const events = [
+      { id: 'e0', seq: 0, ts: 1, sessionId: id, turnId: 't1', source: 'user', type: 'user_prompt', text: 'hi' },
+      { id: 'e1', seq: 1, ts: 2, sessionId: id, turnId: 't1', source: 'model', type: 'assistant_message', content: 'hello', stopReason: 'end_turn' },
+      { id: 'e2', seq: 2, ts: 3, sessionId: id, turnId: 't1', source: 'compactor', type: 'compaction', compactor: 'x', replacedRange: [0, 1], summary: 's', tokensSaved: 10 },
+    ];
+    const original = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+    await fs.writeFile(path.join(dir, `${id}.jsonl`), original, 'utf8');
+
+    const { logger, lines } = captureLogger();
+    const restored = await restoreEvents(id, dir, logger);
+
+    expect(restored).toEqual(events);
+    expect(lines).toHaveLength(0);
+    // No repair rewrite for a clean log — the bytes on disk are untouched.
+    expect(await fs.readFile(path.join(dir, `${id}.jsonl`), 'utf8')).toBe(original);
+  });
+
+  it('readEventPage skips wrong-shape lines like corrupt ones (read-only, no rewrite)', async () => {
+    const dir = await makeTempDir();
+    const id = '01PAGEBADSHAPE000000000000';
+    const mk = (seq: number, text: string) => ({
+      id: `e${seq}`,
+      seq,
+      ts: seq,
+      sessionId: id,
+      turnId: 't1',
+      source: 'user',
+      type: 'user_prompt',
+      text,
+    });
+    const lines = [
+      JSON.stringify(mk(0, 'zero')),
+      JSON.stringify({ notAnEvent: true }),
+      JSON.stringify(mk(1, 'one')),
+      '{corrupt',
+      JSON.stringify(mk(2, 'two')),
+    ];
+    const original = lines.join('\n') + '\n';
+    await fs.writeFile(path.join(dir, `${id}.jsonl`), original, 'utf8');
+
+    const page = await readEventPage(id, { before: null, limit: 10 }, dir);
+    expect(page.events.map((e) => e.seq)).toEqual([0, 1, 2]);
+    expect(page.prevCursor).toBeNull();
+    // Read-only: the junk stays on disk (restore owns the repair).
+    expect(await fs.readFile(path.join(dir, `${id}.jsonl`), 'utf8')).toBe(original);
+  });
+
+  it('readIndex hydration ignores a wrong-shape line when recovering firstPrompt', async () => {
+    const dir = await makeTempDir();
+    await fs.mkdir(dir, { recursive: true });
+    const id = '01HYDRATEBADSHAPE000000000';
+    await fs.writeFile(
+      path.join(dir, `${id}.json`),
+      JSON.stringify({ ...meta(id, 3), firstPrompt: null }, null, 2),
+      'utf8',
+    );
+    const junkPrompt = JSON.stringify({ type: 'user_prompt', text: 'junk without envelope' });
+    const validPrompt = JSON.stringify({
+      id: 'e1',
+      seq: 1,
+      ts: 2,
+      sessionId: id,
+      turnId: 't1',
+      source: 'user',
+      type: 'user_prompt',
+      text: 'real prompt',
+    });
+    await fs.writeFile(path.join(dir, `${id}.jsonl`), junkPrompt + '\n' + validPrompt + '\n', 'utf8');
+
+    const [restored] = await readIndex(dir);
+
+    // The junk line neither becomes the label nor hides the later valid prompt.
+    expect(restored?.firstPrompt).toBe('real prompt');
+    expect(restored?.eventCount).toBe(1);
+  });
+
   it('restore removes foreign-session events, creates a backup, and re-sequences survivors', async () => {
     const dir = await makeTempDir();
     const id = '01RESTOREFILTER000000000';

package/src/sessions/persistence.ts

@@ -22,12 +22,14 @@ import { createMutex, type Mutex, type MoxxyEvent, type SessionId } from '@moxxy
 import type { EventLogLike, EventPage, SessionMeta, SessionSource } from '@moxxy/sdk';
 import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
 import { createLogger, type Logger } from '../logger.js';
+import { isMoxxyEventShape } from './event-shape.js';
 
 // `SessionSource`, `SessionMeta` and `EventPage` are the EventStore contract's
 // data shapes — defined in @moxxy/sdk so `EventStoreDef` can reference them.
 // Re-exported here (and onward from @moxxy/core) so existing importers are
 // unaffected by the move.
 export type { EventLogLike, EventPage, SessionMeta, SessionSource } from '@moxxy/sdk';
+export { SESSION_SOURCES } from '@moxxy/sdk';
 
 /** Schema version of the per-session metadata file (`<id>.json`). Bump when the
  *  shape changes incompatibly; readers tolerate a missing/older version. */
@@ -529,7 +531,10 @@ async function matchingSessionStatsFromLog(
   for (const line of raw.split('\n')) {
     if (!line.trim()) continue;
     try {
-      events.push(JSON.parse(line) as MoxxyEvent);
+      const parsed: unknown = JSON.parse(line);
+      // Wrong-shape lines are skipped exactly like corrupt ones: neither a
+      // corrupt nor a junk line should hide a later valid prompt.
+      if (isMoxxyEventShape(parsed)) events.push(parsed);
     } catch {
       // A corrupt line should not hide a later valid prompt.
     }
@@ -549,10 +554,11 @@ function providerHeaderFromEvent(event: MoxxyEvent): { provider?: string | null;
  * Restore a previously-persisted session's events. Returns the full
  * event array suitable for passing into `new EventLog(events)`.
  *
- * Skips malformed lines (a single corrupted append shouldn't make the
- * rest of the conversation unreadable) and then RE-SEQUENCES the
- * survivors to contiguous `seq` 0..n-1, preserving order and ids. This
- * matters twice over:
+ * Skips malformed lines — corrupt JSON and valid-JSON-but-wrong-shape
+ * alike (see {@link isMoxxyEventShape}); a single bad append shouldn't
+ * make the rest of the conversation unreadable — and then RE-SEQUENCES
+ * the survivors to contiguous `seq` 0..n-1, preserving order and ids.
+ * This matters twice over:
  *
  *  - Mirror replay: `EventLog.ingest` accepts only `seq === length`, so
  *    a gap left by one corrupt middle line would silently truncate every
@@ -584,15 +590,25 @@ export async function restoreEvents(
   }
   const events: MoxxyEvent[] = [];
   let corruptLines = 0;
+  let invalidShapeLines = 0;
   let foreignEvents = 0;
   let normalizedSessionIds = 0;
   for (const line of raw.split('\n')) {
     if (!line.trim()) continue;
     try {
-      const event = JSON.parse(line) as MoxxyEvent;
-      const ownedEvent = eventForSession(event, sessionId);
+      const parsed: unknown = JSON.parse(line);
+      // Valid JSON but not a replayable event shape (see isMoxxyEventShape):
+      // skipped with the exact same semantics as a corrupt line — counted,
+      // re-sequenced around, and repaired away by the rewrite below. Casting
+      // it through instead used to let a junk line drive replay (a compaction
+      // line without `replacedRange` throws mid-projection).
+      if (!isMoxxyEventShape(parsed)) {
+        invalidShapeLines += 1;
+        continue;
+      }
+      const ownedEvent = eventForSession(parsed, sessionId);
       if (ownedEvent) {
-        if (ownedEvent !== event) normalizedSessionIds += 1;
+        if (ownedEvent !== parsed) normalizedSessionIds += 1;
         events.push(ownedEvent);
       } else {
         foreignEvents += 1;
@@ -612,7 +628,13 @@ export async function restoreEvents(
     }
   }
 
-  if (corruptLines > 0 || resequenced > 0 || foreignEvents > 0 || normalizedSessionIds > 0) {
+  if (
+    corruptLines > 0 ||
+    invalidShapeLines > 0 ||
+    resequenced > 0 ||
+    foreignEvents > 0 ||
+    normalizedSessionIds > 0
+  ) {
     const message =
       foreignEvents > 0
         ? 'session log restored with foreign-session events removed — re-sequenced to keep full history replayable'
@@ -621,6 +643,7 @@ export async function restoreEvents(
       sessionId,
       path: logPath,
       corruptLines,
+      invalidShapeLines,
       foreignEvents,
       normalizedSessionIds,
       resequencedEvents: resequenced,
@@ -695,7 +718,7 @@ export async function restoreEvents(
  * `prevCursor` is the `seq` of the page's oldest event, or `null` once the
  * first persisted event is included (no older page remains).
  *
- * Corrupt lines are skipped (matching {@link restoreEvents}); unlike
+ * Corrupt and wrong-shape lines are skipped (matching {@link restoreEvents}); unlike
  * `restoreEvents` this is a READ-ONLY reader — it never rewrites the file, so
  * it preserves the JSONL exactly (no atomic-write / mutex needed: there is no
  * mutation). Paging keys on each event's on-disk `seq`. Determinism holds for a
@@ -724,13 +747,16 @@ export async function readEventPage(
     return { events: [], prevCursor: null };
   }
 
-  // Parse the JSONL, skipping corrupt lines (one bad append must not make the
-  // rest unreadable). Read-only: we never rewrite the file here.
+  // Parse the JSONL, skipping corrupt AND wrong-shape lines (one bad append
+  // must not make the rest unreadable). Read-only: we never rewrite the file
+  // here.
   const all: MoxxyEvent[] = [];
   for (const line of raw.split('\n')) {
     if (!line.trim()) continue;
     try {
-      all.push(JSON.parse(line) as MoxxyEvent);
+      const parsed: unknown = JSON.parse(line);
+      // skip a valid-JSON-but-not-an-event line, same as restoreEvents
+      if (isMoxxyEventShape(parsed)) all.push(parsed);
     } catch {
       // skip a malformed/half-written line, same as restoreEvents
     }

package/src/skill-usage.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadSkillUsage, mergeSkillUsage } from './skill-usage.js';
+
+let tmpDir: string;
+let usagePath: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-skill-usage-'));
+  usagePath = path.join(tmpDir, 'usage.json');
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('skill-usage store', () => {
+  it('returns an empty aggregate when the file is missing', async () => {
+    const file = await loadSkillUsage(usagePath);
+    expect(file.skills).toEqual({});
+    expect(file.version).toBe(1);
+  });
+
+  it('merges a delta and round-trips through disk', async () => {
+    await mergeSkillUsage(
+      { 'deploy-app': { invocations: 2, lastInvokedAt: '2026-07-03T10:00:00.000Z' } },
+      usagePath,
+    );
+    const file = await loadSkillUsage(usagePath);
+    expect(file.skills['deploy-app']!.invocations).toBe(2);
+    expect(file.skills['deploy-app']!.lastInvokedAt).toBe('2026-07-03T10:00:00.000Z');
+  });
+
+  it('accumulates invocations across merges and advances lastInvokedAt', async () => {
+    await mergeSkillUsage(
+      { 'deploy-app': { invocations: 1, lastInvokedAt: '2026-07-01T00:00:00.000Z' } },
+      usagePath,
+    );
+    await mergeSkillUsage(
+      { 'deploy-app': { invocations: 3, lastInvokedAt: '2026-07-02T00:00:00.000Z' } },
+      usagePath,
+    );
+    const file = await loadSkillUsage(usagePath);
+    expect(file.skills['deploy-app']!.invocations).toBe(4);
+    // The later timestamp wins even if a merge arrives out of order.
+    expect(file.skills['deploy-app']!.lastInvokedAt).toBe('2026-07-02T00:00:00.000Z');
+  });
+
+  it('keeps the earliest createdAt and never lets a later merge overwrite it', async () => {
+    await mergeSkillUsage(
+      { 'deploy-app': { invocations: 0, createdAt: '2026-06-01T00:00:00.000Z' } },
+      usagePath,
+    );
+    await mergeSkillUsage(
+      { 'deploy-app': { invocations: 1, createdAt: '2026-07-01T00:00:00.000Z' } },
+      usagePath,
+    );
+    const file = await loadSkillUsage(usagePath);
+    expect(file.skills['deploy-app']!.createdAt).toBe('2026-06-01T00:00:00.000Z');
+    expect(file.skills['deploy-app']!.invocations).toBe(1);
+  });
+
+  it('does not advance lastInvokedAt when an out-of-order (earlier) delta arrives', async () => {
+    await mergeSkillUsage(
+      { s: { invocations: 1, lastInvokedAt: '2026-07-05T00:00:00.000Z' } },
+      usagePath,
+    );
+    await mergeSkillUsage(
+      { s: { invocations: 1, lastInvokedAt: '2026-07-01T00:00:00.000Z' } },
+      usagePath,
+    );
+    const file = await loadSkillUsage(usagePath);
+    expect(file.skills['s']!.lastInvokedAt).toBe('2026-07-05T00:00:00.000Z');
+    expect(file.skills['s']!.invocations).toBe(2);
+  });
+
+  it('an empty delta is a no-op read (does not create the file)', async () => {
+    const file = await mergeSkillUsage({}, usagePath);
+    expect(file.skills).toEqual({});
+    await expect(fs.access(usagePath)).rejects.toThrow();
+  });
+
+  it('falls back to empty on a corrupt (unparseable) file', async () => {
+    await fs.writeFile(usagePath, '{ this is not json');
+    expect((await loadSkillUsage(usagePath)).skills).toEqual({});
+  });
+
+  it('falls back to empty on a shape-invalid file (non-numeric counter)', async () => {
+    // A hand-edited file with a string counter must not flow into the additive
+    // merge (which would corrupt the aggregate via string concatenation).
+    await fs.writeFile(
+      usagePath,
+      JSON.stringify({ version: 1, updatedAt: 'x', skills: { s: { invocations: '5' } } }),
+    );
+    expect((await loadSkillUsage(usagePath)).skills).toEqual({});
+    // A subsequent merge therefore starts fresh rather than concatenating.
+    await mergeSkillUsage({ s: { invocations: 2 } }, usagePath);
+    expect((await loadSkillUsage(usagePath)).skills['s']!.invocations).toBe(2);
+  });
+});