pi-braid 0.43.5 → 0.43.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/CHANGELOG.md +95 -7
  2. package/build-info.json +4 -4
  3. package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +1 -1
  4. package/dist/extensions/core/prompt-builder/surface-discipline-section.js +1 -1
  5. package/dist/extensions/core/skills-tool/applicability.d.ts +134 -0
  6. package/dist/extensions/core/skills-tool/applicability.js +161 -0
  7. package/dist/extensions/core/skills-tool/auto-inject.d.ts +10 -0
  8. package/dist/extensions/core/skills-tool/auto-inject.js +216 -1
  9. package/dist/extensions/core/skills-tool/index.js +64 -3
  10. package/dist/extensions/core/skills-tool/loading-guidance.js +2 -1
  11. package/dist/extensions/core/skills-tool/session-records.d.ts +297 -8
  12. package/dist/extensions/core/skills-tool/session-records.js +509 -5
  13. package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
  14. package/dist/extensions/core/skills-tool/skill-families.js +105 -0
  15. package/dist/extensions/orchestrator/index.js +11 -1
  16. package/docs/LOCAL_DEV.md +1 -1
  17. package/package.json +1 -1
  18. package/src/extensions/core/AGENTS.md +1 -0
  19. package/src/extensions/core/prompt-builder/surface-discipline-section.ts +1 -1
  20. package/src/extensions/core/skills-tool/applicability.ts +220 -0
  21. package/src/extensions/core/skills-tool/auto-inject.ts +274 -0
  22. package/src/extensions/core/skills-tool/index.ts +75 -2
  23. package/src/extensions/core/skills-tool/loading-guidance.ts +2 -1
  24. package/src/extensions/core/skills-tool/session-records.ts +740 -5
  25. package/src/extensions/core/skills-tool/skill-families.ts +112 -0
  26. package/src/extensions/orchestrator/index.ts +13 -1
@@ -1,8 +1,18 @@
1
1
  /**
2
- * Durable per-session skill-adoption records + monthly adoption rollup.
2
+ * Durable per-session skill records + the monthly adoption rollup.
3
3
  *
4
- * Every session that reaches an agent turn gets ONE logical record:
5
- * { sessionId, role, month, hadSkillLoad, updatedAt }
4
+ * The store is one append-only JSONL file with three record kinds, told apart
5
+ * by `kind`:
6
+ *
7
+ * (absent) an ADOPTION record, the older shape:
8
+ * { sessionId, role, month, hadSkillLoad, updatedAt }
9
+ * "applicability" an APPLICABILITY record: the session's skill verdicts
10
+ * (see ApplicabilityRecord)
11
+ * "obligation" an OBLIGATION record: one skill's legs in one session
12
+ * (see ObligationLegRecord)
13
+ *
14
+ * An adoption record exists for every session that reaches an agent turn, so
15
+ * every such session gets ONE logical record (the rollup denominator);
6
16
  * `role` carries the session's profile name from the braid config (see
7
17
  * lib/config/session-profiles.ts), or the neutral default when no profile
8
18
  * matches; `month` is the local-time "YYYY-MM" of the write, and
@@ -22,6 +32,13 @@
22
32
  * filesystems; the tolerant reader skips unparseable lines, the window is
23
33
  * a single small write, and this is accepted as best-effort telemetry.
24
34
  *
35
+ * Each reader reads its own kind and ignores the others. The adoption reader
36
+ * is fail-closed on an unknown `kind`, so a record type added later cannot
37
+ * enter the adoption numbers by looking enough like one; and a build that
38
+ * predates the applicability kind reads those lines as adoption records of
39
+ * the same session, which folds to the same numbers because it carries no
40
+ * new sessions and never sets `hadSkillLoad`.
41
+ *
25
42
  * Back-compat: records written before profiles existed carry a role from
26
43
  * the retired fixed set; those values pass the profile-name gate
27
44
  * unchanged, so older buckets keep folding under their original names.
@@ -41,6 +58,8 @@ import {
41
58
  resolveSessionProfileForCwd,
42
59
  type ResolvedSessionProfile,
43
60
  } from "../../../lib/config/session-profiles.js";
61
+ import { MAX_APPLICABILITY_EVIDENCE } from "./applicability.js";
62
+ import type { ApplicabilityEvidence, SkillApplicabilityVerdict } from "./applicability.js";
44
63
 
45
64
  const log = createLogger("skills-tool");
46
65
 
@@ -72,6 +91,9 @@ export function monthOf(date: Date): string {
72
91
  function normalizeRecord(raw: unknown): SkillSessionRecord | undefined {
73
92
  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
74
93
  const r = raw as Record<string, unknown>;
94
+ // One file, several record kinds: the adoption reader accepts its own kind
95
+ // (no `kind`, or an explicit "adoption") and refuses anything else.
96
+ if (r.kind !== undefined && r.kind !== "adoption") return undefined;
75
97
  if (typeof r.sessionId !== "string" || !r.sessionId) return undefined;
76
98
  if (typeof r.month !== "string" || !/^\d{4}-\d{2}$/.test(r.month)) return undefined;
77
99
  const role = normalizeProfileName(r.role) ?? NEUTRAL_SESSION_PROFILE;
@@ -135,11 +157,11 @@ export function readSessionRecords(storePath: string): SkillSessionRecord[] {
135
157
  }
136
158
 
137
159
  /**
138
- * Append one record. Best-effort: every error is swallowed (this runs on
160
+ * Append one record line. Best-effort: every error is swallowed (this runs on
139
161
  * the agent-loop and tool-result paths — a telemetry failure must never
140
162
  * break a turn). Returns true when the line landed on disk.
141
163
  */
142
- export function appendSessionRecord(record: SkillSessionRecord, storePath: string): boolean {
164
+ function appendLine(record: object, storePath: string): boolean {
143
165
  try {
144
166
  mkdirSync(dirname(storePath), { recursive: true });
145
167
  appendFileSync(storePath, `${JSON.stringify(record)}\n`, "utf-8");
@@ -150,6 +172,11 @@ export function appendSessionRecord(record: SkillSessionRecord, storePath: strin
150
172
  }
151
173
  }
152
174
 
175
+ /** Append one adoption record (see appendLine for the failure contract). */
176
+ export function appendSessionRecord(record: SkillSessionRecord, storePath: string): boolean {
177
+ return appendLine(record, storePath);
178
+ }
179
+
153
180
  /** Warned once per process about a refused adoption-record append. */
154
181
  let _warnedRecordFailure = false;
155
182
 
@@ -253,6 +280,714 @@ export function recordSessionSkillLoad(ctx: ExtensionContext, storePath?: string
253
280
  }
254
281
  }
255
282
 
283
+ // Applicability records (the verdict kind)
284
+
285
+ /**
286
+ * One skill's applicability verdict for one session.
287
+ *
288
+ * The three classes, as this instrument names them:
289
+ *
290
+ * not-applicable the skill's own declared condition did not meet the
291
+ * session's task text. Derived, never a row: the census's
292
+ * `evaluated` minus the verdict rows. A row per non-match
293
+ * would multiply every session's record by the installed
294
+ * catalog to say "nothing here".
295
+ * ignored the condition held and no detected read followed. This is
296
+ * the class the adoption counters cannot express.
297
+ * read the condition held and a detected SKILL.md read followed.
298
+ *
299
+ * `undeclared` sits outside all three: those skill files state no condition, so
300
+ * no verdict about them is honest (see applicability.ts).
301
+ */
302
+
303
+ /** One verdict row: the skill, its class, and the phrases that decided it. */
304
+ export interface ApplicabilityVerdictRecord {
305
+ kind: "applicability";
306
+ sessionId: string;
307
+ role: string;
308
+ month: string;
309
+ updatedAt: string;
310
+ /** The skill this row answers for. */
311
+ skill: string;
312
+ /** read | ignored — a row exists only where a condition held. */
313
+ applicability: "read" | "ignored";
314
+ evidence: ApplicabilityEvidence[];
315
+ }
316
+
317
+ /**
318
+ * One session's census row: how much task text was read, how many skills
319
+ * declared a condition, and which ones declared none. Written once per
320
+ * session, so `not-applicable` is derivable without a row per non-match.
321
+ */
322
+ export interface ApplicabilityCensusRecord {
323
+ kind: "applicability";
324
+ sessionId: string;
325
+ role: string;
326
+ month: string;
327
+ updatedAt: string;
328
+ /** Characters of task text the first evaluation read. */
329
+ taskChars: number;
330
+ /** Installed skills declaring at least one condition phrase. */
331
+ evaluated: number;
332
+ /** Installed skills whose files declare no condition phrase. */
333
+ undeclared: string[];
334
+ }
335
+
336
+ /**
337
+ * An applicability record. The two shapes share the kind and the session
338
+ * identity, and a reader tells them apart by `skill`: a row with one answers
339
+ * for that skill, a row without one is the session's census. The split is what
340
+ * lets a per-skill record join the sibling compliance record on
341
+ * (sessionId, skill) without either store learning the other's fields.
342
+ */
343
+ export type ApplicabilityRecord = ApplicabilityVerdictRecord | ApplicabilityCensusRecord;
344
+
345
+ /** A session's applicability after folding every record written for it. */
346
+ export interface SessionApplicability {
347
+ sessionId: string;
348
+ role: string;
349
+ month: string;
350
+ updatedAt: string;
351
+ /** Characters of task text the census read. */
352
+ taskChars: number;
353
+ /** Skills that declared a condition. */
354
+ evaluated: number;
355
+ /** Skills that declared none — the blind spot, named. */
356
+ undeclared: string[];
357
+ /** One entry per applicable skill, `read` beating `ignored`. */
358
+ verdicts: SkillApplicabilityVerdict[];
359
+ /** The three classes as counts: read + ignored = applicable. */
360
+ classes: { read: number; ignored: number; notApplicable: number };
361
+ }
362
+
363
+ /** One evidence row, normalizing an unknown source to "no source recorded". */
364
+ function normalizeEvidence(raw: unknown): ApplicabilityEvidence | undefined {
365
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
366
+ const e = raw as Record<string, unknown>;
367
+ if (typeof e.phrase !== "string" || !e.phrase) return undefined;
368
+ return e.source === "frontmatter" || e.source === "heading" || e.source === "description"
369
+ ? { phrase: e.phrase, source: e.source }
370
+ : { phrase: e.phrase };
371
+ }
372
+
373
+ /**
374
+ * Normalize one raw applicability line; undefined when the line is not one.
375
+ * Field junk is coerced to a safe default rather than trusted, matching the
376
+ * adoption reader's posture.
377
+ */
378
+ function normalizeApplicabilityRecord(raw: unknown): ApplicabilityRecord | undefined {
379
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
380
+ const r = raw as Record<string, unknown>;
381
+ if (r.kind !== "applicability") return undefined;
382
+ if (typeof r.sessionId !== "string" || !r.sessionId) return undefined;
383
+ if (typeof r.month !== "string" || !/^\d{4}-\d{2}$/.test(r.month)) return undefined;
384
+ const base = {
385
+ kind: "applicability" as const,
386
+ sessionId: r.sessionId,
387
+ role: normalizeProfileName(r.role) ?? NEUTRAL_SESSION_PROFILE,
388
+ month: r.month,
389
+ updatedAt: typeof r.updatedAt === "string" ? r.updatedAt : "",
390
+ };
391
+ if (typeof r.skill === "string" && r.skill) {
392
+ if (r.applicability !== "read" && r.applicability !== "ignored") return undefined;
393
+ const evidence: ApplicabilityEvidence[] = [];
394
+ for (const item of Array.isArray(r.evidence) ? r.evidence : []) {
395
+ const normalized = normalizeEvidence(item);
396
+ if (normalized) evidence.push(normalized);
397
+ }
398
+ return { ...base, skill: r.skill, applicability: r.applicability, evidence };
399
+ }
400
+ const count = (value: unknown): number =>
401
+ typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
402
+ return {
403
+ ...base,
404
+ taskChars: count(r.taskChars),
405
+ evaluated: count(r.evaluated),
406
+ undeclared: (Array.isArray(r.undeclared) ? r.undeclared : []).filter(
407
+ (name): name is string => typeof name === "string" && name !== "",
408
+ ),
409
+ };
410
+ }
411
+
412
+ /**
413
+ * Read the applicability records from the store. Missing or unreadable file →
414
+ * empty (never throws); non-applicability and corrupt lines are skipped.
415
+ */
416
+ export function readApplicabilityRecords(storePath: string): ApplicabilityRecord[] {
417
+ let text: string;
418
+ try {
419
+ text = readFileSync(storePath, "utf-8");
420
+ } catch {
421
+ return []; // missing or unreadable → no records
422
+ }
423
+ const out: ApplicabilityRecord[] = [];
424
+ for (const line of text.split("\n")) {
425
+ const trimmed = line.trim();
426
+ if (!trimmed) continue;
427
+ try {
428
+ const rec = normalizeApplicabilityRecord(JSON.parse(trimmed));
429
+ if (rec) out.push(rec);
430
+ } catch {
431
+ // torn or corrupt line — skip
432
+ }
433
+ }
434
+ return out;
435
+ }
436
+
437
+ /**
438
+ * Merge two verdicts for the same skill: `read` beats `ignored` (a read is
439
+ * evidence the skill's content reached the session, whatever the turn order
440
+ * was), and the evidence unions by (phrase, source), bounded like every other
441
+ * evidence surface. Pure.
442
+ */
443
+ function mergeVerdict(
444
+ current: SkillApplicabilityVerdict | undefined,
445
+ next: SkillApplicabilityVerdict,
446
+ ): SkillApplicabilityVerdict {
447
+ if (!current) return next;
448
+ const byPhrase = new Map<string, ApplicabilityEvidence>();
449
+ for (const evidence of [...current.evidence, ...next.evidence]) {
450
+ const key = `${evidence.phrase}\u0000${evidence.source ?? ""}`;
451
+ if (!byPhrase.has(key) && byPhrase.size < MAX_APPLICABILITY_EVIDENCE) {
452
+ byPhrase.set(key, evidence);
453
+ }
454
+ }
455
+ return {
456
+ name: next.name,
457
+ verdict: current.verdict === "read" || next.verdict === "read" ? "read" : "ignored",
458
+ evidence: [...byPhrase.values()],
459
+ };
460
+ }
461
+
462
+ /**
463
+ * Fold the store into one logical record per sessionId: the newest census wins
464
+ * the session facts, verdict rows union across writes with `read` beating
465
+ * `ignored`. Pure. The fold is what makes a torn, duplicated or out-of-order
466
+ * append harmless: the record set, not the line order, decides a verdict.
467
+ */
468
+ export function foldApplicabilityRecords(records: ApplicabilityRecord[]): SessionApplicability[] {
469
+ const byId = new Map<string, SessionApplicability>();
470
+ const empty = (rec: ApplicabilityRecord): SessionApplicability => ({
471
+ sessionId: rec.sessionId,
472
+ role: rec.role,
473
+ month: rec.month,
474
+ updatedAt: rec.updatedAt,
475
+ taskChars: 0,
476
+ evaluated: 0,
477
+ undeclared: [],
478
+ verdicts: [],
479
+ classes: { read: 0, ignored: 0, notApplicable: 0 },
480
+ });
481
+ for (const rec of records) {
482
+ const prev = byId.get(rec.sessionId) ?? empty(rec);
483
+ // Session facts come from the newest CENSUS row; verdict rows carry no
484
+ // census of their own and must not erase it.
485
+ const newer = rec.updatedAt >= prev.updatedAt;
486
+ const verdicts = new Map(prev.verdicts.map((v) => [v.name, v]));
487
+ if ("skill" in rec) {
488
+ verdicts.set(
489
+ rec.skill,
490
+ mergeVerdict(verdicts.get(rec.skill), {
491
+ name: rec.skill,
492
+ verdict: rec.applicability,
493
+ evidence: rec.evidence,
494
+ }),
495
+ );
496
+ }
497
+ const census = "evaluated" in rec ? (newer ? rec : undefined) : undefined;
498
+ byId.set(rec.sessionId, {
499
+ sessionId: rec.sessionId,
500
+ role: newer ? rec.role : prev.role,
501
+ month: newer ? rec.month : prev.month,
502
+ updatedAt: newer ? rec.updatedAt : prev.updatedAt,
503
+ taskChars: census ? census.taskChars : prev.taskChars,
504
+ evaluated: census ? census.evaluated : prev.evaluated,
505
+ undeclared: census ? census.undeclared : prev.undeclared,
506
+ verdicts: [...verdicts.values()],
507
+ classes: { read: 0, ignored: 0, notApplicable: 0 },
508
+ });
509
+ }
510
+ for (const rec of byId.values()) {
511
+ const read = rec.verdicts.filter((v) => v.verdict === "read").length;
512
+ const ignored = rec.verdicts.length - read;
513
+ rec.classes = { read, ignored, notApplicable: Math.max(0, rec.evaluated - read - ignored) };
514
+ }
515
+ return [...byId.values()];
516
+ }
517
+
518
+ /** Fields a caller supplies for the session's census row. */
519
+ export interface ApplicabilityCensusInput {
520
+ taskChars: number;
521
+ evaluated: number;
522
+ undeclared: string[];
523
+ }
524
+
525
+ /** Resolve the session identity a record needs, or undefined for a fake ctx. */
526
+ function applicabilityBase(
527
+ ctx: ExtensionContext,
528
+ ): { sessionId: string; role: string; month: string; updatedAt: string } | undefined {
529
+ const sess = resolveSession(ctx);
530
+ if (!sess) return undefined;
531
+ return {
532
+ sessionId: sess.sessionId,
533
+ role: getSessionProfile(ctx).name,
534
+ month: monthOf(new Date()),
535
+ updatedAt: new Date().toISOString(),
536
+ };
537
+ }
538
+
539
+ /**
540
+ * Append the session's census row. Best-effort like every other writer here: a
541
+ * false return means the line did not land, never a thrown turn.
542
+ */
543
+ export function recordApplicabilityCensus(
544
+ ctx: ExtensionContext,
545
+ census: ApplicabilityCensusInput,
546
+ storePath?: string,
547
+ ): boolean {
548
+ try {
549
+ const base = applicabilityBase(ctx);
550
+ if (!base) return false;
551
+ return appendLine(
552
+ { kind: "applicability", ...base, ...census },
553
+ storePath ?? getSkillsSessionsFilePath(),
554
+ );
555
+ } catch (err) {
556
+ reportRecordFailure(err);
557
+ return false;
558
+ }
559
+ }
560
+
561
+ /**
562
+ * Append one skill's verdict row. The same function writes the `read` upgrade:
563
+ * the fold decides, so no line is ever rewritten.
564
+ */
565
+ export function recordApplicabilityVerdict(
566
+ ctx: ExtensionContext,
567
+ verdict: { skill: string; applicability: "read" | "ignored"; evidence: ApplicabilityEvidence[] },
568
+ storePath?: string,
569
+ ): boolean {
570
+ try {
571
+ const base = applicabilityBase(ctx);
572
+ if (!base) return false;
573
+ return appendLine(
574
+ { kind: "applicability", ...base, ...verdict },
575
+ storePath ?? getSkillsSessionsFilePath(),
576
+ );
577
+ } catch (err) {
578
+ reportRecordFailure(err);
579
+ return false;
580
+ }
581
+ }
582
+
583
+ /**
584
+ * The folded applicability record for the context's own session, or undefined
585
+ * when the session wrote none. Reader: a refused path or a torn store is a
586
+ * miss, not a throw.
587
+ */
588
+ export function getSessionApplicability(
589
+ ctx: ExtensionContext,
590
+ options: { storePath?: string } = {},
591
+ ): SessionApplicability | undefined {
592
+ try {
593
+ const sess = resolveSession(ctx);
594
+ if (!sess) return undefined;
595
+ const storePath = options.storePath ?? getSkillsSessionsFilePath();
596
+ return foldApplicabilityRecords(readApplicabilityRecords(storePath)).find(
597
+ (rec) => rec.sessionId === sess.sessionId,
598
+ );
599
+ } catch (err) {
600
+ reportRecordFailure(err);
601
+ return undefined;
602
+ }
603
+ }
604
+
605
+ // Obligation records (the applied leg)
606
+
607
+ /**
608
+ * One skill's legs in one session: what the instrument saw happen to the body
609
+ * an obligation names.
610
+ *
611
+ * These are facts about reads and calls, not verdicts. `read` here means a
612
+ * DETECTED SKILL.md read, and it is deliberately not the applicability record's
613
+ * `applicability: "read"` class — that one is a verdict about a skill whose
614
+ * declared condition held, and the applicability record refuses to classify a
615
+ * read whose condition never held. This record states the read and leaves the
616
+ * verdict where it belongs.
617
+ *
618
+ * `called` and `applied` are the applied leg, and they are the reason the
619
+ * record exists:
620
+ * called a tool call in a family this skill declares happened this
621
+ * session, whatever the call's outcome — a refusal fires before the
622
+ * call and cannot know the result.
623
+ * applied the FIRST such call came after a detected read of this body.
624
+ *
625
+ * The pair is decided once, at the first call, because that is the only moment
626
+ * the ordering exists: a later read followed by a later call must not turn an
627
+ * earlier violation into satisfaction. Both stay false when the skill declares
628
+ * no family; most declare none, and an obligation that names no family is
629
+ * satisfied by the read alone.
630
+ *
631
+ * `suggested` and `listed` are the surfaces that made the body findable in
632
+ * this session (a delivered suggestion, a list_skills row); they carry the
633
+ * "was it offered" half of adoption, which the call facts cannot.
634
+ */
635
+ export interface ObligationLegRecord {
636
+ kind: "obligation";
637
+ sessionId: string;
638
+ role: string;
639
+ month: string;
640
+ updatedAt: string;
641
+ skill: string;
642
+ suggested: boolean;
643
+ listed: boolean;
644
+ read: boolean;
645
+ called: boolean;
646
+ applied: boolean;
647
+ }
648
+
649
+ /** A record's five legs, read back as one row per skill. */
650
+ export interface ObligationLegs {
651
+ skill: string;
652
+ suggested: boolean;
653
+ listed: boolean;
654
+ read: boolean;
655
+ called: boolean;
656
+ applied: boolean;
657
+ }
658
+
659
+ /** One session's obligation rows, folded. */
660
+ export interface SessionObligation {
661
+ sessionId: string;
662
+ role: string;
663
+ month: string;
664
+ updatedAt: string;
665
+ /** One row per skill seen, in first-seen order. */
666
+ skills: ObligationLegs[];
667
+ }
668
+
669
+ /** Normalize a parsed JSON line into an obligation record, or null. */
670
+ export function normalizeObligationRecord(raw: unknown): ObligationLegRecord | null {
671
+ if (!raw || typeof raw !== "object") return null;
672
+ const r = raw as Record<string, unknown>;
673
+ if (r.kind !== "obligation") return null;
674
+ if (typeof r.sessionId !== "string" || typeof r.skill !== "string" || !r.skill.trim()) {
675
+ return null;
676
+ }
677
+ return {
678
+ kind: "obligation",
679
+ sessionId: r.sessionId,
680
+ role: typeof r.role === "string" ? r.role : NEUTRAL_SESSION_PROFILE,
681
+ month: typeof r.month === "string" ? r.month : "",
682
+ updatedAt: typeof r.updatedAt === "string" ? r.updatedAt : "",
683
+ skill: r.skill,
684
+ suggested: r.suggested === true,
685
+ listed: r.listed === true,
686
+ read: r.read === true,
687
+ called: r.called === true,
688
+ applied: r.applied === true,
689
+ };
690
+ }
691
+
692
+ /**
693
+ * Read the obligation records from the store. Missing or unreadable file →
694
+ * empty (never throws); other kinds and corrupt lines are skipped.
695
+ */
696
+ export function readObligationRecords(
697
+ storePath: string = getSkillsSessionsFilePath(),
698
+ ): ObligationLegRecord[] {
699
+ let text: string;
700
+ try {
701
+ text = readFileSync(storePath, "utf-8");
702
+ } catch {
703
+ return []; // missing or unreadable → no records
704
+ }
705
+ const out: ObligationLegRecord[] = [];
706
+ for (const line of text.split("\n")) {
707
+ const trimmed = line.trim();
708
+ if (!trimmed) continue;
709
+ try {
710
+ const rec = normalizeObligationRecord(JSON.parse(trimmed));
711
+ if (rec) out.push(rec);
712
+ } catch {
713
+ // torn or corrupt line — skip
714
+ }
715
+ }
716
+ return out;
717
+ }
718
+
719
+ /**
720
+ * Fold a session's obligation rows into one record: the five legs OR across
721
+ * every row, so a row that saw one leg never erases a leg a later row did not
722
+ * have. `called`/`applied` are written once per skill, so the OR is exact
723
+ * rather than convenient. A torn or duplicated row folds; a malformed one is
724
+ * dropped at normalize, before this sees it.
725
+ */
726
+ export function foldObligationRecords(records: ObligationLegRecord[]): SessionObligation[] {
727
+ const bySession = new Map<string, SessionObligation>();
728
+ for (const rec of records) {
729
+ let session = bySession.get(rec.sessionId);
730
+ if (!session) {
731
+ session = {
732
+ sessionId: rec.sessionId,
733
+ role: rec.role,
734
+ month: rec.month,
735
+ updatedAt: rec.updatedAt,
736
+ skills: [],
737
+ };
738
+ bySession.set(rec.sessionId, session);
739
+ } else if (rec.updatedAt >= session.updatedAt) {
740
+ session.role = rec.role;
741
+ session.month = rec.month;
742
+ session.updatedAt = rec.updatedAt;
743
+ }
744
+ const held = session.skills.find((legs) => legs.skill === rec.skill);
745
+ if (!held) {
746
+ session.skills.push({
747
+ skill: rec.skill,
748
+ suggested: rec.suggested,
749
+ listed: rec.listed,
750
+ read: rec.read,
751
+ called: rec.called,
752
+ applied: rec.applied,
753
+ });
754
+ continue;
755
+ }
756
+ held.suggested = held.suggested || rec.suggested;
757
+ held.listed = held.listed || rec.listed;
758
+ held.read = held.read || rec.read;
759
+ held.called = held.called || rec.called;
760
+ held.applied = held.applied || rec.applied;
761
+ }
762
+ return [...bySession.values()];
763
+ }
764
+
765
+ /**
766
+ * Append one skill's legs. Best-effort like the sibling writer: a refused or
767
+ * missing store returns false so the caller can retry on a later turn.
768
+ */
769
+ export function recordObligationLegs(
770
+ ctx: ExtensionContext,
771
+ legs: ObligationLegs,
772
+ storePath?: string,
773
+ ): boolean {
774
+ try {
775
+ const base = applicabilityBase(ctx);
776
+ if (!base) return false;
777
+ const record: ObligationLegRecord = {
778
+ kind: "obligation",
779
+ ...base,
780
+ skill: legs.skill,
781
+ suggested: legs.suggested,
782
+ listed: legs.listed,
783
+ read: legs.read,
784
+ called: legs.called,
785
+ applied: legs.applied,
786
+ };
787
+ return appendLine(record, storePath ?? getSkillsSessionsFilePath());
788
+ } catch (err) {
789
+ reportRecordFailure(err);
790
+ return false;
791
+ }
792
+ }
793
+
794
+ /** The current session's obligation rows, folded. Missing store → undefined. */
795
+ export function getSessionObligation(
796
+ ctx: ExtensionContext,
797
+ options: { storePath?: string } = {},
798
+ ): SessionObligation | undefined {
799
+ try {
800
+ const sess = resolveSession(ctx);
801
+ if (!sess) return undefined;
802
+ const storePath = options.storePath ?? getSkillsSessionsFilePath();
803
+ return foldObligationRecords(readObligationRecords(storePath)).find(
804
+ (rec) => rec.sessionId === sess.sessionId,
805
+ );
806
+ } catch (err) {
807
+ reportRecordFailure(err);
808
+ return undefined;
809
+ }
810
+ }
811
+
812
+ /**
813
+ * An obligation is satisfied when the body was read AND, if the session ever
814
+ * called into a family the skill declares, that the first call came after the
815
+ * read. Without a declared family the second clause is vacuous: reading the
816
+ * body is the whole obligation.
817
+ */
818
+ export function obligationSatisfied(legs: ObligationLegs): boolean {
819
+ return legs.read && (!legs.called || legs.applied);
820
+ }
821
+
822
+ /** One judged skill: its legs, plus whether it was even an obligation. */
823
+ export interface JudgedSkill extends ObligationLegs {
824
+ /** null when the skill's declared condition never held: no obligation. */
825
+ satisfied: boolean | null;
826
+ }
827
+
828
+ /** A session's judgement: every leg it recorded, and the session boolean. */
829
+ export interface SessionJudgement {
830
+ skills: JudgedSkill[];
831
+ allSatisfied: boolean;
832
+ /** Obligations that applied (leg rows whose condition held). */
833
+ obligations: number;
834
+ }
835
+
836
+ /**
837
+ * Judge one session against its obligation rows. Pure.
838
+ *
839
+ * A skill is an obligation when the applicability fold carries a verdict for
840
+ * it: the previous record's question was whether the skill applied, and this
841
+ * one takes that answer as given. An obligation is decided by this record's
842
+ * legs alone, which is why the two kinds can be folded independently and
843
+ * joined on (sessionId, skill) without either re-reading the other.
844
+ */
845
+ export function judgeSessionObligations(
846
+ applicable: SessionApplicability | undefined,
847
+ obligation: SessionObligation | undefined,
848
+ ): SessionJudgement | undefined {
849
+ if (!applicable) return undefined;
850
+ const applied = new Set(applicable.verdicts.map((verdict) => verdict.name));
851
+ const skills: JudgedSkill[] = (obligation?.skills ?? []).map((legs) => ({
852
+ ...legs,
853
+ satisfied: applied.has(legs.skill) ? obligationSatisfied(legs) : null,
854
+ }));
855
+ // An applicable skill with no leg row still owes the read: a session that was
856
+ // never offered, listed, or read the body it owed is the ignored population,
857
+ // and dropping it from the denominator would report only the sessions that
858
+ // happened to be instrumented.
859
+ const seen = new Set(skills.map((legs) => legs.skill));
860
+ for (const skill of applied) {
861
+ if (seen.has(skill)) continue;
862
+ skills.push({
863
+ skill,
864
+ suggested: false,
865
+ listed: false,
866
+ read: false,
867
+ called: false,
868
+ applied: false,
869
+ satisfied: false,
870
+ });
871
+ }
872
+ if (!applicable.verdicts.length) {
873
+ return { skills, allSatisfied: false, obligations: 0 };
874
+ }
875
+ const obligations = skills.filter((legs) => legs.satisfied !== null);
876
+ return {
877
+ skills,
878
+ obligations: obligations.length,
879
+ allSatisfied: obligations.every((legs) => legs.satisfied === true),
880
+ };
881
+ }
882
+
883
+ /**
884
+ * The design's own decision rule: a gap this small makes the rate a duplicate
885
+ * of the read rate, and a duplicate should be deleted rather than shipped.
886
+ */
887
+ export const FALSIFIER_GAP_POINTS = 5;
888
+
889
+ /**
890
+ * The two rates and their shared denominator.
891
+ *
892
+ * `sessions` is the population both rates are divided by: sessions with at
893
+ * least one obligation that applied AND at least one obligation row, i.e. the
894
+ * sessions this build's instrument saw. A session whose applicable verdicts
895
+ * predate the instrument is counted in `uninstrumented` instead of scored as
896
+ * unsatisfied — a zero the instrument did not observe is not a zero it found.
897
+ *
898
+ * `readRate` is the older measurement restricted to this population: a session
899
+ * counts when ANY detected read landed in it, which is the adoption counter's
900
+ * own definition (`actual > 0`), so the difference between the two numbers is
901
+ * the satisfaction criterion and nothing else.
902
+ */
903
+ export interface ObligationRate {
904
+ sessions: number;
905
+ allSatisfied: number;
906
+ /** 0-1, rounded to 4 decimals (a percentage point is 2 of these). */
907
+ allSatisfiedRate: number;
908
+ withRead: number;
909
+ readRate: number;
910
+ /** allSatisfiedRate - readRate, in percentage points, 2 decimals. */
911
+ gapPoints: number;
912
+ /** Obligations that applied, across the population. */
913
+ obligations: number;
914
+ unsatisfied: number;
915
+ /** False when the gap is under FALSIFIER_GAP_POINTS: the metric is a copy. */
916
+ discriminating: boolean;
917
+ /** Sessions with an applicable skill but no obligation row: not scored. */
918
+ uninstrumented: number;
919
+ }
920
+
921
+ /** Compute both rates over one store's folds. Pure. */
922
+ export function computeObligationRate(
923
+ sessions: SessionApplicability[],
924
+ obligations: SessionObligation[],
925
+ ): ObligationRate {
926
+ const bySession = new Map(obligations.map((rec) => [rec.sessionId, rec]));
927
+ let population = 0;
928
+ let allSatisfied = 0;
929
+ let withRead = 0;
930
+ let obligationsSeen = 0;
931
+ let unsatisfied = 0;
932
+ let uninstrumented = 0;
933
+ for (const session of sessions) {
934
+ if (!session.verdicts.length) continue;
935
+ const legs = bySession.get(session.sessionId);
936
+ if (!legs || !legs.skills.length) {
937
+ uninstrumented++;
938
+ continue;
939
+ }
940
+ const judgement = judgeSessionObligations(session, legs);
941
+ if (!judgement) continue;
942
+ population++;
943
+ obligationsSeen += judgement.obligations;
944
+ if (judgement.allSatisfied) allSatisfied++;
945
+ if (legs.skills.some((row) => row.read)) withRead++;
946
+ unsatisfied += judgement.skills.filter((row) => row.satisfied === false).length;
947
+ }
948
+ const allSatisfiedRate = population ? round4(allSatisfied / population) : 0;
949
+ const readRate = population ? round4(withRead / population) : 0;
950
+ const gapPoints = Math.round((allSatisfiedRate - readRate) * 10000) / 100;
951
+ return {
952
+ sessions: population,
953
+ allSatisfied,
954
+ allSatisfiedRate,
955
+ withRead,
956
+ readRate,
957
+ gapPoints,
958
+ obligations: obligationsSeen,
959
+ unsatisfied,
960
+ discriminating: Math.abs(gapPoints) >= FALSIFIER_GAP_POINTS,
961
+ uninstrumented,
962
+ };
963
+ }
964
+
965
+ function round4(n: number): number {
966
+ return Math.round(n * 10000) / 10000;
967
+ }
968
+
969
+ /**
970
+ * The store-wide rate, or undefined when the store carries no obligation row
971
+ * at all. Undefined is the absent record: a reader of a store this build has
972
+ * not written to sees the payload it always saw, byte for byte.
973
+ */
974
+ export function getObligationRate(
975
+ options: { storePath?: string } = {},
976
+ ): ObligationRate | undefined {
977
+ try {
978
+ const storePath = options.storePath ?? getSkillsSessionsFilePath();
979
+ const obligationRecords = readObligationRecords(storePath);
980
+ if (!obligationRecords.length) return undefined;
981
+ return computeObligationRate(
982
+ foldApplicabilityRecords(readApplicabilityRecords(storePath)),
983
+ foldObligationRecords(obligationRecords),
984
+ );
985
+ } catch (err) {
986
+ reportRecordFailure(err);
987
+ return undefined;
988
+ }
989
+ }
990
+
256
991
  /** Adoption numbers for one profile in one month. */
257
992
  export interface ProfileAdoption {
258
993
  /** Sessions active in the month (records with a turn). */