feat(linkedin-studio): N16 — out-of-network-andel + patterns-oppdatering + boundary-map [skip-docs]

Reach-splitten (in/out-of-network) er native i LinkedIns post-analytics siden juni
2026, men vises som PROSENT og finnes ikke i CSV-eksporten. Planen antok to
manuelle antall; verifiseringen viste prosent, så modellen er ett felt —
outOfNetworkPct — og in-network er komplementet.

- parseOptionalPercent: egen parser, ikke parseOptionalCount. Komma er desimal
  (36,5 -> 36.5, aldri 365), og verdi >100 avvises: i én kolonne kan ikke et
  absolutt antall skilles fra en andel, så svaret er unknown, ikke en gjetning.
  Blank/ikke-numerisk/negativ -> unknown; ekte 0 beholdes.
- Ett lagret halvpart, kryssjekket: In-network godtas og lagres som komplement;
  et transkribert par som ikke summerer til ~100 (±1 avrunding) forkastes som
  unknown i stedet for å bli halvveis trodd.
- weightedOutOfNetworkPct: impressions-vektet roll-up (avgOutOfNetworkPct, uke +
  måned). Flatt snitt lar en 50-visnings-post slå en på 10 000; poster uten
  avlesning ekskluderes, og null vekt gir undefined — aldri 0, aldri NaN.
- Reach inngår ALDRI i engagementRate (distribusjon != engasjement). Rapporten
  leser den som akvisisjon (ut) vs resonans (inn), og sier «ikke ført for denne
  perioden» framfor å estimere. En reach-innsikt går inn i N15s do-next-kanal.
- Step 7c (A2-F11): rapporten tilbyr diff mot brukerens engagement-patterns.md
  med eksplisitt go — aldri stille skriving, aldri inn i den shippede malen.
- Boundary-map (E#9): dwell eksplisitt umålbar, saves partner-gated, reach
  native men CSV-eksport uverifisert.
- Reach-frie importer er byte-identiske med før, på skjerm og på disk.

TDD: rødt bevist først (10 feilende), analytics 119 -> 144 tester, tsc ren.
test-runner 232 -> 247 (Section 16w, gulv 213 -> 228). Alle suiter grønne.
CHANGELOG: N15-oppføringen manglet og er backfilt sammen med N16.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QxvWAjte7vPcF79QeSRvRJ

scripts/analytics/src/cli.ts

@@ -6,7 +6,7 @@ import {
   loadAllPosts,
 } from "./utils/storage.js";
 import { detectAlerts } from "./utils/alerts.js";
-import { mean, standardDeviation } from "./utils/stats.js";
+import { mean, standardDeviation, weightedOutOfNetworkPct } from "./utils/stats.js";
 import { generateWeeklyReport, getCurrentISOWeek } from "./reports/weekly.js";
 import { generateHeatmap } from "./reports/heatmap.js";
 import { generateMonthlyReport } from "./reports/monthly.js";
@@ -30,6 +30,19 @@ function savesSuffix(saves?: number): string {
   return saves !== undefined ? ` | ${saves.toLocaleString()} saves` : "";
 }
 
+/**
+ * Per-post reach suffix. Empty string when the post carries no manual
+ * out-of-network share, so reach-free output stays identical to the pre-N16 CLI.
+ */
+function reachSuffix(outOfNetworkPct?: number): string {
+  return outOfNetworkPct !== undefined ? ` | ${outOfNetworkPct}% out-of-network` : "";
+}
+
+/** Round to one decimal — keeps the derived in-network half free of float noise. */
+function round1(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
 function printUsage() {
   console.log(`
 LinkedIn Analytics CLI
@@ -90,6 +103,15 @@ async function handleImport(root: string, args: string[]) {
       console.log(`Saves entered:   ${totalSaves.toLocaleString()} across ${savesPosts.length} post(s) (manual)`);
     }
 
+    // Same for the reach split when the CSV carried an Out-of-network (or
+    // In-network) column. Counting the posts that carry a reading makes partial
+    // coverage visible instead of implying the whole batch was transcribed.
+    const reachPosts = batch.posts.filter((p) => p.metrics.outOfNetworkPct !== undefined);
+    if (reachPosts.length > 0) {
+      const weighted = weightedOutOfNetworkPct(batch.posts);
+      console.log(`Reach entered:   ${weighted}% out-of-network across ${reachPosts.length} post(s) (manual, impressions-weighted)`);
+    }
+
     // Run alert detection on imported posts
     const alerts = detectAlerts(batch.posts, "impressions");
 
@@ -144,6 +166,10 @@ async function handleReport(root: string, args: string[]) {
     if (report.summary.totalSaves !== undefined) {
       console.log(`Total saves:         ${report.summary.totalSaves.toLocaleString()} (manual entry — top engagement signal)`);
     }
+    if (report.summary.avgOutOfNetworkPct !== undefined) {
+      console.log(`Out-of-network:      ${report.summary.avgOutOfNetworkPct}% of impressions (manual entry — acquisition signal)`);
+      console.log(`In-network:          ${round1(100 - report.summary.avgOutOfNetworkPct)}% of impressions (resonance with the audience you have)`);
+    }
     console.log(`Avg engagement:      ${report.summary.avgEngagementRate.toFixed(2)}%`);
     console.log(`Avg impressions:     ${Math.round(report.summary.avgImpressionsPerPost).toLocaleString()} per post`);
     console.log();
@@ -154,7 +180,7 @@ async function handleReport(root: string, args: string[]) {
       for (const post of report.topPerformers.slice(0, 5)) {
         const title = post.title.length > 50 ? post.title.substring(0, 47) + "..." : post.title;
         console.log(`• ${title}`);
-        console.log(`  ${post.metrics.impressions.toLocaleString()} impressions | ${post.metrics.engagementRate.toFixed(2)}% engagement${savesSuffix(post.metrics.saves)} | ${post.publishedDate}`);
+        console.log(`  ${post.metrics.impressions.toLocaleString()} impressions | ${post.metrics.engagementRate.toFixed(2)}% engagement${savesSuffix(post.metrics.saves)}${reachSuffix(post.metrics.outOfNetworkPct)} | ${post.publishedDate}`);
       }
       console.log();
     }
@@ -165,7 +191,7 @@ async function handleReport(root: string, args: string[]) {
       for (const post of report.underperformers.slice(0, 3)) {
         const title = post.title.length > 50 ? post.title.substring(0, 47) + "..." : post.title;
         console.log(`• ${title}`);
-        console.log(`  ${post.metrics.impressions.toLocaleString()} impressions | ${post.metrics.engagementRate.toFixed(2)}% engagement${savesSuffix(post.metrics.saves)} | ${post.publishedDate}`);
+        console.log(`  ${post.metrics.impressions.toLocaleString()} impressions | ${post.metrics.engagementRate.toFixed(2)}% engagement${savesSuffix(post.metrics.saves)}${reachSuffix(post.metrics.outOfNetworkPct)} | ${post.publishedDate}`);
       }
       console.log();
     }
@@ -342,6 +368,10 @@ async function handleMonthlyReport(root: string, month: string) {
     if (s.totalSaves !== undefined) {
       console.log(`Saves:               ${s.totalSaves.toLocaleString()} (manual entry — top engagement signal)`);
     }
+    if (s.avgOutOfNetworkPct !== undefined) {
+      console.log(`Out-of-network:      ${s.avgOutOfNetworkPct}% of impressions (manual entry — acquisition signal)`);
+      console.log(`In-network:          ${round1(100 - s.avgOutOfNetworkPct)}% of impressions (resonance with the audience you have)`);
+    }
     console.log();
 
     if (report.byWeek.length > 0) {
@@ -359,7 +389,7 @@ async function handleMonthlyReport(root: string, month: string) {
       for (const post of report.topPerformers.slice(0, 5)) {
         const title = post.title.length > 50 ? post.title.substring(0, 47) + "..." : post.title;
         console.log(`• ${title}`);
-        console.log(`  ${post.metrics.impressions.toLocaleString()} impressions | ${post.metrics.engagementRate.toFixed(2)}% eng${savesSuffix(post.metrics.saves)} | ${post.publishedDate}`);
+        console.log(`  ${post.metrics.impressions.toLocaleString()} impressions | ${post.metrics.engagementRate.toFixed(2)}% eng${savesSuffix(post.metrics.saves)}${reachSuffix(post.metrics.outOfNetworkPct)} | ${post.publishedDate}`);
       }
       console.log();
     }

scripts/analytics/src/models/types.ts

@@ -23,6 +23,24 @@ export interface PostMetrics {
   // It is deliberately NOT folded into engagementRate (which stays comparable
   // to historical, saves-free data) — saves is surfaced as its own signal.
   saves?: number;
+  // `outOfNetworkPct` is OPTIONAL and manually entered — the share (0–100) of a
+  // post's impressions that came from people who did NOT follow or connect with
+  // the author. LinkedIn shows the in-network/out-of-network split natively in
+  // post analytics (Discovery section, under Impressions; progressive global
+  // rollout from June 2026) as a PERCENTAGE split, and does NOT put it in the
+  // CSV export — so the ingest is a percent cell the user adds to the CSV, read
+  // off that panel (see csv-parser.ts).
+  //
+  // Only the out-of-network half is stored: in-network is its complement by
+  // definition (they describe one split), so keeping both would allow a
+  // self-contradicting record. A missing column, a blank cell, a non-numeric
+  // cell, a negative, or a value above 100 stays undefined — "unknown", never
+  // coerced to 0; a genuine 0 is kept as 0 (nothing left the network).
+  //
+  // NOT folded into engagementRate: reach is a distribution signal, not
+  // engagement. High out-of-network = the post acquired new audience; high
+  // in-network engagement = it deepened the existing one.
+  outOfNetworkPct?: number;
   // NOTE: `dwell` remains absent and unmeasurable. Dwell time is internal to
   // LinkedIn for organic posts — not exportable, no UI count to transcribe, no
   // API. Do not fabricate a dwell field or surface.
@@ -48,6 +66,10 @@ export interface WeeklyReport {
     totalShares: number;
     totalClicks: number;
     totalSaves?: number; // optional — present only when ≥1 post carries manual saves data
+    // Optional — present only when ≥1 post carries a manual out-of-network share.
+    // Impressions-WEIGHTED, so a small post with a high share cannot outvote a
+    // large one (see weightedOutOfNetworkPct).
+    avgOutOfNetworkPct?: number;
     avgEngagementRate: number;
     avgImpressionsPerPost: number;
   };
@@ -122,6 +144,9 @@ export interface MonthlyReport {
     totalShares: number;
     totalClicks: number;
     totalSaves?: number; // optional — present only when ≥1 post carries manual saves data
+    // Optional — present only when ≥1 post carries a manual out-of-network share
+    // (impressions-weighted; see weightedOutOfNetworkPct).
+    avgOutOfNetworkPct?: number;
     avgEngagementRate: number;
     avgImpressionsPerPost: number;
   };

scripts/analytics/src/parsers/csv-parser.ts

@@ -84,6 +84,64 @@ function parseOptionalCount(value: string): number | undefined {
   return parsed;
 }
 
+/**
+ * Rounding slack, in percentage points, allowed between the two halves of the
+ * reach split. LinkedIn rounds each half independently for display, so a
+ * transcribed "63% / 37%" can legitimately sum to 99 or 101.
+ */
+const REACH_SPLIT_TOLERANCE = 1;
+
+/** Round to one decimal — the UI reading is itself a rounded percentage. */
+function round1(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+/**
+ * Parse an OPTIONAL manually-entered PERCENTAGE share (out-of-network reach).
+ * Distinct from parseOptionalCount in two ways that matter:
+ *   - a share never carries a thousands separator, so a comma is always the
+ *     DECIMAL mark here ("36,5" → 36.5). parseOptionalCount's US-thousands rule
+ *     would read that as 365.
+ *   - a share above 100 is not a share. It is most likely an absolute
+ *     impression count pasted into a percent column, and one column cannot tell
+ *     a count from a share — so the honest answer is unknown, never a guess.
+ * Otherwise the same contract as the saves field:
+ *   - blank / absent / non-numeric / negative → undefined ("unknown", never 0)
+ *   - a genuine "0"                           → 0 (nothing left the network)
+ *   - "37%", "37 %", "37"                     → 37
+ */
+function parseOptionalPercent(value: string): number | undefined {
+  if (!value) return undefined;
+  const cleaned = value.replace(/"/g, "").replace(/%/g, "").trim();
+  if (cleaned === "") return undefined;
+
+  const parsed = Number(cleaned.replace(/,/g, "."));
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 100) return undefined;
+  return round1(parsed);
+}
+
+/**
+ * Reduce whichever halves of the reach split the user transcribed to the single
+ * stored value: the out-of-network share.
+ *   - out-of-network only → that value
+ *   - in-network only     → its complement (they describe one split)
+ *   - both, consistent    → the out-of-network reading
+ *   - both, contradictory → undefined. One cell is a misreading and we cannot
+ *     tell which, so the record stays unknown rather than silently trusting one.
+ */
+function resolveOutOfNetworkPct(
+  outOfNetwork: number | undefined,
+  inNetwork: number | undefined
+): number | undefined {
+  if (outOfNetwork !== undefined && inNetwork !== undefined) {
+    const sum = outOfNetwork + inNetwork;
+    return Math.abs(sum - 100) <= REACH_SPLIT_TOLERANCE ? outOfNetwork : undefined;
+  }
+  if (outOfNetwork !== undefined) return outOfNetwork;
+  if (inNetwork !== undefined) return round1(100 - inNetwork);
+  return undefined;
+}
+
 /**
  * Normalizes date to YYYY-MM-DD format
  * Handles: DD.MM.YYYY, MM/DD/YYYY, YYYY-MM-DD
@@ -225,6 +283,19 @@ export function parseLinkedInCSV(
         metrics.saves = saves;
       }
 
+      // Optional manual-entry reach split: only when the user augmented this CSV
+      // with an Out-of-network (or In-network) column, read off the native
+      // Discovery panel in post analytics — LinkedIn does not export it. Either
+      // half is accepted and reduced to the out-of-network share; anything
+      // unreadable or self-contradicting stays undefined ("unknown", never 0).
+      const outOfNetworkPct = resolveOutOfNetworkPct(
+        parseOptionalPercent(findColumn(record, ["out-of-network", "out of network", "outofnetwork"])),
+        parseOptionalPercent(findColumn(record, ["in-network", "in network", "innetwork"]))
+      );
+      if (outOfNetworkPct !== undefined) {
+        metrics.outOfNetworkPct = outOfNetworkPct;
+      }
+
       return {
         id: generatePostId(title, date),
         title,

scripts/analytics/src/reports/monthly.ts

@@ -1,6 +1,6 @@
 import type { PostAnalytics, MonthlyReport } from "../models/types.js";
 import { loadAllPosts, loadMonthlyReport, saveMonthlyReport } from "../utils/storage.js";
-import { mean } from "../utils/stats.js";
+import { mean, weightedOutOfNetworkPct } from "../utils/stats.js";
 import { detectAlerts } from "../utils/alerts.js";
 import { getISOWeek } from "./weekly.js";
 
@@ -34,6 +34,9 @@ export function generateMonthlyReport(root: string, month: string): MonthlyRepor
   const totalSaves = savesPosts.length > 0
     ? savesPosts.reduce((s, p) => s + (p.metrics.saves ?? 0), 0)
     : undefined;
+  // Optional out-of-network share: impressions-weighted, present only when ≥1
+  // post carries a reading — keeps reach-free months identical to pre-N16 output.
+  const avgOutOfNetworkPct = weightedOutOfNetworkPct(monthPosts);
   const avgEngagementRate = totalPosts > 0
     ? parseFloat(mean(monthPosts.map(p => p.metrics.engagementRate)).toFixed(2))
     : 0;
@@ -108,6 +111,7 @@ export function generateMonthlyReport(root: string, month: string): MonthlyRepor
       totalShares,
       totalClicks,
       ...(totalSaves !== undefined ? { totalSaves } : {}),
+      ...(avgOutOfNetworkPct !== undefined ? { avgOutOfNetworkPct } : {}),
       avgEngagementRate,
       avgImpressionsPerPost,
     },

scripts/analytics/src/reports/weekly.ts

@@ -1,5 +1,5 @@
 import type { PostAnalytics, WeeklyReport } from "../models/types.js";
-import { mean, trendDirection, percentChange } from "../utils/stats.js";
+import { mean, trendDirection, percentChange, weightedOutOfNetworkPct } from "../utils/stats.js";
 import { detectAlerts, detectWeeklyAlerts } from "../utils/alerts.js";
 import { loadAllPosts, loadWeeklyReport, saveWeeklyReport } from "../utils/storage.js";
 
@@ -173,6 +173,14 @@ export function generateWeeklyReport(analyticsRoot: string, week?: string): Week
     report.summary.totalSaves = totalSaves;
   }
 
+  // Same contract for the out-of-network share: impressions-weighted, and only
+  // present when at least one post carried a reading (reach-free reports stay
+  // byte-identical to pre-N16 output).
+  const avgOutOfNetworkPct = weightedOutOfNetworkPct(weekPosts);
+  if (avgOutOfNetworkPct !== undefined) {
+    report.summary.avgOutOfNetworkPct = avgOutOfNetworkPct;
+  }
+
   // Calculate averages
   const engagementRates = weekPosts.map(post => post.metrics.engagementRate);
   report.summary.avgEngagementRate = mean(engagementRates);

scripts/analytics/src/utils/stats.ts

@@ -50,6 +50,43 @@ export function percentChange(current: number, previous: number): number {
   return ((current - previous) / previous) * 100;
 }
 
+/**
+ * Minimal shape needed to weight a reach share — keeps this helper usable from
+ * both report builders without dragging in the full PostAnalytics record.
+ */
+interface ReachWeightable {
+  metrics: { impressions: number; outOfNetworkPct?: number };
+}
+
+/**
+ * Roll per-post out-of-network shares up to one number, WEIGHTED by impressions.
+ *
+ * The share is a fraction of a post's own impressions, so a flat mean would let
+ * a 50-impression post at 90% outvote a 10,000-impression post at 20%. Posts
+ * without a share are excluded entirely — folding them in as 0 would invent
+ * data that was never entered.
+ *
+ * Returns undefined when no post carries a share, or when the posts that do
+ * carry one have no impressions to weight (a share of zero impressions has no
+ * meaning; 0 would be a fabricated reading and NaN a bug).
+ */
+export function weightedOutOfNetworkPct(posts: ReachWeightable[]): number | undefined {
+  let totalWeight = 0;
+  let weightedSum = 0;
+  let sawShare = false;
+
+  for (const post of posts) {
+    const pct = post.metrics.outOfNetworkPct;
+    if (pct === undefined) continue;
+    sawShare = true;
+    totalWeight += post.metrics.impressions;
+    weightedSum += post.metrics.impressions * pct;
+  }
+
+  if (!sawShare || totalWeight <= 0) return undefined;
+  return Math.round((weightedSum / totalWeight) * 10) / 10;
+}
+
 /**
  * Calculate how many standard deviations a value is from the mean.
  * Returns 0 if standard deviation is 0.

scripts/analytics/tests/csv-parser.test.ts

@@ -191,3 +191,189 @@ describe("Saves (manual-entry, optional)", () => {
     );
   });
 });
+
+/**
+ * Out-of-network reach (manual-entry, optional) — N16.
+ *
+ * LinkedIn surfaces the in-network/out-of-network split natively in post
+ * analytics (Discovery section, under Impressions; progressive global rollout
+ * from June 2026) as a PERCENTAGE split — not as two absolute counts, and not
+ * in the CSV export. So the ingest is a percent cell the operator transcribes,
+ * and the stored field is a single share: `outOfNetworkPct`. In-network is its
+ * complement by definition, so storing both halves would only invite a
+ * self-contradicting record.
+ */
+describe("Out-of-network reach (manual-entry, optional)", () => {
+  it("should parse an Out-of-network percent cell written with a % suffix", () => {
+    const filePath = join(fixturesDir, "reach-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-export.csv");
+
+    assert.equal(batch.postCount, 4, "Should have 4 posts");
+    assert.equal(
+      batch.posts[0].metrics.outOfNetworkPct,
+      37,
+      "'37%' must parse to the number 37"
+    );
+  });
+
+  it("should leave outOfNetworkPct undefined when the cell is blank (unknown != zero)", () => {
+    const filePath = join(fixturesDir, "reach-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-export.csv");
+
+    assert.equal(
+      batch.posts[1].metrics.outOfNetworkPct,
+      undefined,
+      "Blank Out-of-network cell must stay undefined, never coerced to 0"
+    );
+  });
+
+  it("should treat an explicit '0' as a genuine zero share (nothing left the network)", () => {
+    const filePath = join(fixturesDir, "reach-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-export.csv");
+
+    assert.equal(
+      batch.posts[2].metrics.outOfNetworkPct,
+      0,
+      "Explicit '0' is a real reading — must stay 0, not collapse to undefined"
+    );
+  });
+
+  it("should read a European decimal comma as a decimal, not a thousands separator", () => {
+    const filePath = join(fixturesDir, "reach-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-export.csv");
+
+    // A share never carries a thousands separator, so "36,5" is 36.5 percent.
+    // parseOptionalCount's US-thousands rule would read this as 365 — wrong here.
+    assert.equal(
+      batch.posts[3].metrics.outOfNetworkPct,
+      36.5,
+      "'36,5' must parse to 36.5 percent, never 365"
+    );
+  });
+
+  it("should leave outOfNetworkPct undefined for a standard export with no reach column (backward-compat)", () => {
+    const filePath = join(fixturesDir, "sample-export.csv");
+    const batch = parseLinkedInCSV(filePath, "sample-export.csv");
+
+    for (const post of batch.posts) {
+      assert.equal(
+        post.metrics.outOfNetworkPct,
+        undefined,
+        "Existing CSV exports without a reach column must round-trip unchanged"
+      );
+    }
+  });
+
+  it("should leave outOfNetworkPct undefined for a non-numeric cell (unknown, never 0)", () => {
+    const filePath = join(fixturesDir, "reach-edge-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-edge-export.csv");
+
+    assert.equal(
+      batch.posts[0].metrics.outOfNetworkPct,
+      undefined,
+      "Non-numeric reach cell must stay undefined — never coerced to 0"
+    );
+  });
+
+  it("should refuse a value above 100 — a count and a share are undecidable in one column", () => {
+    const filePath = join(fixturesDir, "reach-edge-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-edge-export.csv");
+
+    // "1234" in a share column is almost certainly an absolute impression count.
+    // We cannot tell which, so the honest answer is unknown — never a guess.
+    assert.equal(
+      batch.posts[1].metrics.outOfNetworkPct,
+      undefined,
+      "A share above 100 must stay undefined, never stored as-is"
+    );
+  });
+
+  it("should leave outOfNetworkPct undefined for a negative cell", () => {
+    const filePath = join(fixturesDir, "reach-edge-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-edge-export.csv");
+
+    assert.equal(
+      batch.posts[2].metrics.outOfNetworkPct,
+      undefined,
+      "A negative share is not a real reading — must stay undefined"
+    );
+  });
+
+  it("should accept exactly 100 as a real reading (the boundary is inclusive)", () => {
+    const filePath = join(fixturesDir, "reach-edge-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-edge-export.csv");
+
+    assert.equal(
+      batch.posts[3].metrics.outOfNetworkPct,
+      100,
+      "100 percent out-of-network is possible and must be kept"
+    );
+  });
+
+  it("should derive outOfNetworkPct from an In-network column as its complement", () => {
+    const filePath = join(fixturesDir, "reach-in-network-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-in-network-export.csv");
+
+    // The operator transcribed the other half of the same split.
+    assert.equal(
+      batch.posts[0].metrics.outOfNetworkPct,
+      37,
+      "'In-network 63%' must store out-of-network 37"
+    );
+    assert.equal(
+      batch.posts[1].metrics.outOfNetworkPct,
+      undefined,
+      "A blank In-network cell leaves neither half known"
+    );
+  });
+
+  it("should keep the out-of-network half when both columns agree", () => {
+    const filePath = join(fixturesDir, "reach-both-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-both-export.csv");
+
+    assert.equal(
+      batch.posts[0].metrics.outOfNetworkPct,
+      37,
+      "63 + 37 = 100 is consistent — keep the out-of-network reading"
+    );
+  });
+
+  it("should refuse a contradictory split rather than pick a half", () => {
+    const filePath = join(fixturesDir, "reach-both-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-both-export.csv");
+
+    // 63 + 20 = 83. One of the two cells is a misreading and we cannot tell
+    // which, so the record stays unknown instead of silently trusting one.
+    assert.equal(
+      batch.posts[1].metrics.outOfNetworkPct,
+      undefined,
+      "A split that does not sum to ~100 must stay undefined"
+    );
+  });
+
+  it("should tolerate one point of rounding slack between the two halves", () => {
+    const filePath = join(fixturesDir, "reach-both-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-both-export.csv");
+
+    // 62 + 37 = 99: the UI rounds each half independently, so a one-point gap
+    // is rounding, not a misreading.
+    assert.equal(
+      batch.posts[2].metrics.outOfNetworkPct,
+      37,
+      "A 99 or 101 sum is rounding slack — keep the out-of-network reading"
+    );
+  });
+
+  it("should NOT fold out-of-network reach into engagementRate", () => {
+    const filePath = join(fixturesDir, "reach-export.csv");
+    const batch = parseLinkedInCSV(filePath, "reach-export.csv");
+
+    // Row 1: (100+30+15+200)/5000 * 100 = 6.9. Reach is a distribution signal,
+    // not engagement — it must not touch the rate.
+    const expectedRate = ((100 + 30 + 15 + 200) / 5000) * 100;
+    assert.ok(
+      Math.abs(batch.posts[0].metrics.engagementRate - expectedRate) < 0.01,
+      `engagementRate should exclude reach (~${expectedRate}), got ${batch.posts[0].metrics.engagementRate}`
+    );
+  });
+});

scripts/analytics/tests/fixtures/reach-both-export.csv

@@ -0,0 +1,4 @@
+"Content","Date","Impressions","Reactions","Comments","Shares","Clicks","In-network","Out-of-network"
+"Both halves transcribed and they sum to 100 - consistent, out-of-network wins...",2026-02-28,2900,70,22,9,130,63%,37%
+"Both halves transcribed but they contradict each other - refuse to guess which one is right...",2026-02-27,2800,70,22,9,130,63%,20%
+"Both halves with rounding slack - 62 + 37 = 99 is within the one-point tolerance...",2026-02-26,2700,70,22,9,130,62%,37%

scripts/analytics/tests/fixtures/reach-edge-export.csv

@@ -0,0 +1,5 @@
+"Content","Date","Impressions","Reactions","Comments","Shares","Clicks","Out-of-network"
+"Non-numeric out-of-network cell - the user jotted a note, not a share; stays unknown...",2026-03-06,3500,70,22,9,130,n/a
+"Above 100 - most likely an absolute impression count pasted into a share column; undecidable, so unknown...",2026-03-05,3400,70,22,9,130,1234
+"Negative share - not a real reading; stays unknown...",2026-03-04,3300,70,22,9,130,-5
+"Exactly 100 - a real reading: every impression came from outside the network...",2026-03-03,3200,70,22,9,130,100

scripts/analytics/tests/fixtures/reach-export.csv

@@ -0,0 +1,5 @@
+"Content","Date","Impressions","Reactions","Comments","Shares","Clicks","Out-of-network"
+"An out-of-network share the user read off the native Discovery panel, with a percent sign...",2026-03-10,5000,100,30,15,200,37%
+"A post where the user left the Out-of-network cell blank - unknown, not zero...",2026-03-09,3000,60,20,8,120,
+"Explicit zero out-of-network - a real reading: nothing left the network...",2026-03-08,4000,80,25,10,150,0
+"A share written with a European decimal comma - 36,5 percent, not 365...",2026-03-07,2000,40,10,5,60,"36,5"

scripts/analytics/tests/fixtures/reach-in-network-export.csv

@@ -0,0 +1,3 @@
+"Content","Date","Impressions","Reactions","Comments","Shares","Clicks","In-network"
+"The user transcribed the in-network half of the split instead - out-of-network is the complement...",2026-03-02,3100,70,22,9,130,63%
+"In-network blank - neither half known...",2026-03-01,3000,60,20,8,120,

scripts/analytics/tests/monthly.test.ts

@@ -104,6 +104,31 @@ describe("generateMonthlyReport", () => {
     assert.equal(report.summary.totalSaves, undefined);
   });
 
+  test("rolls out-of-network shares up as an impressions-weighted average", () => {
+    const withReach = (p: PostAnalytics, outOfNetworkPct: number): PostAnalytics => ({
+      ...p,
+      metrics: { ...p.metrics, outOfNetworkPct },
+    });
+    const posts: PostAnalytics[] = [
+      withReach(createPost("2026-03-03", 10000, 3.0), 20),
+      withReach(createPost("2026-03-05", 1000, 4.0), 80),
+      createPost("2026-03-10", 5000, 3.5), // no share entered — must not dilute
+    ];
+    const root = setupTestRoot(posts);
+    const report = generateMonthlyReport(root, "2026-03");
+    assert.equal(
+      report.summary.avgOutOfNetworkPct,
+      25.5,
+      "Should weight by impressions (25.5), not average the shares flat (50)"
+    );
+  });
+
+  test("leaves avgOutOfNetworkPct undefined for reach-free months (backward-compat)", () => {
+    const root = setupTestRoot(marchPosts);
+    const report = generateMonthlyReport(root, "2026-03");
+    assert.equal(report.summary.avgOutOfNetworkPct, undefined);
+  });
+
   test("generates weekly breakdown within month", () => {
     const root = setupTestRoot(marchPosts);
     const report = generateMonthlyReport(root, "2026-03");

scripts/analytics/tests/stats.test.ts

@@ -6,6 +6,7 @@ import {
   trendDirection,
   percentChange,
   deviationsFromMean,
+  weightedOutOfNetworkPct,
 } from "../src/utils/stats.js";
 
 describe("stats", () => {
@@ -136,4 +137,60 @@ describe("stats", () => {
       assert.ok(Math.abs(result) < 0.01);
     });
   });
+
+  /**
+   * Out-of-network reach aggregate (N16). The share is per-post, so the only
+   * honest roll-up is impressions-weighted: a 50-impression post at 90% must
+   * not outvote a 10,000-impression post at 20%.
+   */
+  describe("weightedOutOfNetworkPct", () => {
+    const post = (impressions: number, outOfNetworkPct?: number) => ({
+      metrics: { impressions, outOfNetworkPct },
+    });
+
+    test("should weight each share by that post's impressions", () => {
+      // (10000*20 + 1000*80) / 11000 = 25.45… — an unweighted mean would say 50.
+      const result = weightedOutOfNetworkPct([post(10000, 20), post(1000, 80)]);
+      assert.equal(result, 25.5, "Should be the impressions-weighted share, not the plain mean");
+    });
+
+    test("should exclude posts that carry no share from the weighting", () => {
+      // The 5000-impression post has no reading; folding it in as 0 would drag
+      // the answer to 17.5 and invent data that was never entered.
+      const result = weightedOutOfNetworkPct([
+        post(10000, 20),
+        post(1000, 80),
+        post(5000, undefined),
+      ]);
+      assert.equal(result, 25.5, "Posts without a share must not dilute the aggregate");
+    });
+
+    test("should keep a genuine 0 share in the weighting", () => {
+      // (1000*0 + 1000*50) / 2000 = 25 — an explicit zero is data, not absence.
+      const result = weightedOutOfNetworkPct([post(1000, 0), post(1000, 50)]);
+      assert.equal(result, 25);
+    });
+
+    test("should return undefined when no post carries a share", () => {
+      const result = weightedOutOfNetworkPct([post(1000), post(2000)]);
+      assert.equal(result, undefined, "Absent data must stay absent, never 0");
+    });
+
+    test("should return undefined for an empty list", () => {
+      assert.equal(weightedOutOfNetworkPct([]), undefined);
+    });
+
+    test("should return undefined when the carrying posts have no impressions", () => {
+      // A share of zero impressions has no meaning, and the weights sum to 0 —
+      // returning 0 here would be a fabricated reading, and NaN a bug.
+      const result = weightedOutOfNetworkPct([post(0, 40)]);
+      assert.equal(result, undefined, "Zero total weight must yield undefined, never NaN or 0");
+    });
+
+    test("should round to one decimal (the UI reading is itself rounded)", () => {
+      // (3000*33.3 + 1000*66.7) / 4000 = 41.65 → 41.7
+      const result = weightedOutOfNetworkPct([post(3000, 33.3), post(1000, 66.7)]);
+      assert.equal(result, 41.7);
+    });
+  });
 });

scripts/analytics/tests/weekly.test.ts

@@ -319,6 +319,57 @@ describe("weekly", () => {
       assert.equal(report.summary.totalSaves, undefined, "Saves-free data must not introduce a totalSaves field");
     });
 
+    test("should roll out-of-network shares up as an impressions-weighted average", () => {
+      tempDir = setupTempDir();
+
+      const posts: PostAnalytics[] = [
+        createTestPost({
+          id: "reach1",
+          publishedDate: "2026-01-12", // 2026-W03
+          metrics: { impressions: 10000, reactions: 500, comments: 100, shares: 50, clicks: 200, engagementRate: 8.5, outOfNetworkPct: 20 },
+        }),
+        createTestPost({
+          id: "reach2",
+          publishedDate: "2026-01-13", // 2026-W03
+          metrics: { impressions: 1000, reactions: 50, comments: 10, shares: 5, clicks: 20, engagementRate: 8.5, outOfNetworkPct: 80 },
+        }),
+        createTestPost({
+          id: "reach3",
+          publishedDate: "2026-01-14", // 2026-W03 — no share entered; must not dilute.
+          metrics: { impressions: 5000, reactions: 250, comments: 50, shares: 25, clicks: 100, engagementRate: 8.5 },
+        }),
+      ];
+
+      saveBatch(tempDir, createTestBatch({ dateRange: { from: "2026-01-12", to: "2026-01-14" }, posts }));
+
+      const report = generateWeeklyReport(tempDir, "2026-W03");
+
+      assert.equal(
+        report.summary.avgOutOfNetworkPct,
+        25.5,
+        "Should weight by impressions (25.5), not average the shares flat (50)"
+      );
+    });
+
+    test("should leave avgOutOfNetworkPct undefined when no post carries a share (backward-compat)", () => {
+      tempDir = setupTempDir();
+
+      const posts: PostAnalytics[] = [
+        createTestPost({ id: "noreach1", publishedDate: "2026-01-12" }),
+        createTestPost({ id: "noreach2", publishedDate: "2026-01-13" }),
+      ];
+
+      saveBatch(tempDir, createTestBatch({ dateRange: { from: "2026-01-12", to: "2026-01-13" }, posts }));
+
+      const report = generateWeeklyReport(tempDir, "2026-W03");
+
+      assert.equal(
+        report.summary.avgOutOfNetworkPct,
+        undefined,
+        "Reach-free data must not introduce an avgOutOfNetworkPct field"
+      );
+    });
+
     test("should identify top performers and underperformers", () => {
       tempDir = setupTempDir();