pi-braid 0.43.6 → 0.43.8
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.
- package/CHANGELOG.md +83 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/applicability.d.ts +134 -0
- package/dist/extensions/core/skills-tool/applicability.js +161 -0
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +31 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +320 -1
- package/dist/extensions/core/skills-tool/index.js +83 -4
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +6 -2
- package/dist/extensions/core/skills-tool/session-records.d.ts +395 -8
- package/dist/extensions/core/skills-tool/session-records.js +645 -5
- package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
- package/dist/extensions/core/skills-tool/skill-families.js +105 -0
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -1
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/applicability.ts +220 -0
- package/src/extensions/core/skills-tool/auto-inject.ts +391 -0
- package/src/extensions/core/skills-tool/index.ts +96 -3
- package/src/extensions/core/skills-tool/loading-guidance.ts +6 -2
- package/src/extensions/core/skills-tool/session-records.ts +932 -5
- package/src/extensions/core/skills-tool/skill-families.ts +112 -0
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- package/src/lib/reasoning/dreamer.ts +13 -6
|
@@ -1,8 +1,18 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Durable per-session skill
|
|
2
|
+
* Durable per-session skill records + the monthly adoption rollup.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
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.
|
|
@@ -30,6 +47,7 @@
|
|
|
30
47
|
*/
|
|
31
48
|
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
32
49
|
import { type ResolvedSessionProfile } from "../../../lib/config/session-profiles.js";
|
|
50
|
+
import type { ApplicabilityEvidence, SkillApplicabilityVerdict } from "./applicability.js";
|
|
33
51
|
/** One durable per-session adoption record (a single JSONL line on disk). */
|
|
34
52
|
export interface SkillSessionRecord {
|
|
35
53
|
/** pi session id (from ctx.sessionManager.getSessionId()). */
|
|
@@ -59,11 +77,7 @@ export declare function foldSessionRecords(records: SkillSessionRecord[]): Skill
|
|
|
59
77
|
* throws); corrupt lines are skipped.
|
|
60
78
|
*/
|
|
61
79
|
export declare function readSessionRecords(storePath: string): SkillSessionRecord[];
|
|
62
|
-
/**
|
|
63
|
-
* Append one record. Best-effort: every error is swallowed (this runs on
|
|
64
|
-
* the agent-loop and tool-result paths — a telemetry failure must never
|
|
65
|
-
* break a turn). Returns true when the line landed on disk.
|
|
66
|
-
*/
|
|
80
|
+
/** Append one adoption record (see appendLine for the failure contract). */
|
|
67
81
|
export declare function appendSessionRecord(record: SkillSessionRecord, storePath: string): boolean;
|
|
68
82
|
/**
|
|
69
83
|
* The session's effective profile, resolved from the braid config on first
|
|
@@ -82,6 +96,379 @@ export declare function recordSessionStart(ctx: ExtensionContext, storePath?: st
|
|
|
82
96
|
* numerator of the adoption rate). Claims must NOT route here.
|
|
83
97
|
*/
|
|
84
98
|
export declare function recordSessionSkillLoad(ctx: ExtensionContext, storePath?: string): void;
|
|
99
|
+
/**
|
|
100
|
+
* One skill's applicability verdict for one session.
|
|
101
|
+
*
|
|
102
|
+
* The three classes, as this instrument names them:
|
|
103
|
+
*
|
|
104
|
+
* not-applicable the skill's own declared condition did not meet the
|
|
105
|
+
* session's task text. Derived, never a row: the census's
|
|
106
|
+
* `evaluated` minus the verdict rows. A row per non-match
|
|
107
|
+
* would multiply every session's record by the installed
|
|
108
|
+
* catalog to say "nothing here".
|
|
109
|
+
* ignored the condition held and no detected read followed. This is
|
|
110
|
+
* the class the adoption counters cannot express.
|
|
111
|
+
* read the condition held and a detected SKILL.md read followed.
|
|
112
|
+
*
|
|
113
|
+
* `undeclared` sits outside all three: those skill files state no condition, so
|
|
114
|
+
* no verdict about them is honest (see applicability.ts).
|
|
115
|
+
*/
|
|
116
|
+
/** One verdict row: the skill, its class, and the phrases that decided it. */
|
|
117
|
+
export interface ApplicabilityVerdictRecord {
|
|
118
|
+
kind: "applicability";
|
|
119
|
+
sessionId: string;
|
|
120
|
+
role: string;
|
|
121
|
+
month: string;
|
|
122
|
+
updatedAt: string;
|
|
123
|
+
/** The skill this row answers for. */
|
|
124
|
+
skill: string;
|
|
125
|
+
/** read | ignored — a row exists only where a condition held. */
|
|
126
|
+
applicability: "read" | "ignored";
|
|
127
|
+
evidence: ApplicabilityEvidence[];
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* One session's census row: how much task text was read, how many skills
|
|
131
|
+
* declared a condition, and which ones declared none. Written once per
|
|
132
|
+
* session, so `not-applicable` is derivable without a row per non-match.
|
|
133
|
+
*/
|
|
134
|
+
export interface ApplicabilityCensusRecord {
|
|
135
|
+
kind: "applicability";
|
|
136
|
+
sessionId: string;
|
|
137
|
+
role: string;
|
|
138
|
+
month: string;
|
|
139
|
+
updatedAt: string;
|
|
140
|
+
/** Characters of task text the first evaluation read. */
|
|
141
|
+
taskChars: number;
|
|
142
|
+
/** Installed skills declaring at least one condition phrase. */
|
|
143
|
+
evaluated: number;
|
|
144
|
+
/** Installed skills whose files declare no condition phrase. */
|
|
145
|
+
undeclared: string[];
|
|
146
|
+
}
|
|
147
|
+
/**
|
|
148
|
+
* An applicability record. The two shapes share the kind and the session
|
|
149
|
+
* identity, and a reader tells them apart by `skill`: a row with one answers
|
|
150
|
+
* for that skill, a row without one is the session's census. The split is what
|
|
151
|
+
* lets a per-skill record join the sibling compliance record on
|
|
152
|
+
* (sessionId, skill) without either store learning the other's fields.
|
|
153
|
+
*/
|
|
154
|
+
export type ApplicabilityRecord = ApplicabilityVerdictRecord | ApplicabilityCensusRecord;
|
|
155
|
+
/** A session's applicability after folding every record written for it. */
|
|
156
|
+
export interface SessionApplicability {
|
|
157
|
+
sessionId: string;
|
|
158
|
+
role: string;
|
|
159
|
+
month: string;
|
|
160
|
+
updatedAt: string;
|
|
161
|
+
/** Characters of task text the census read. */
|
|
162
|
+
taskChars: number;
|
|
163
|
+
/** Skills that declared a condition. */
|
|
164
|
+
evaluated: number;
|
|
165
|
+
/** Skills that declared none — the blind spot, named. */
|
|
166
|
+
undeclared: string[];
|
|
167
|
+
/** One entry per applicable skill, `read` beating `ignored`. */
|
|
168
|
+
verdicts: SkillApplicabilityVerdict[];
|
|
169
|
+
/** The three classes as counts: read + ignored = applicable. */
|
|
170
|
+
classes: {
|
|
171
|
+
read: number;
|
|
172
|
+
ignored: number;
|
|
173
|
+
notApplicable: number;
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Read the applicability records from the store. Missing or unreadable file →
|
|
178
|
+
* empty (never throws); non-applicability and corrupt lines are skipped.
|
|
179
|
+
*/
|
|
180
|
+
export declare function readApplicabilityRecords(storePath: string): ApplicabilityRecord[];
|
|
181
|
+
/**
|
|
182
|
+
* Fold the store into one logical record per sessionId: the newest census wins
|
|
183
|
+
* the session facts, verdict rows union across writes with `read` beating
|
|
184
|
+
* `ignored`. Pure. The fold is what makes a torn, duplicated or out-of-order
|
|
185
|
+
* append harmless: the record set, not the line order, decides a verdict.
|
|
186
|
+
*/
|
|
187
|
+
export declare function foldApplicabilityRecords(records: ApplicabilityRecord[]): SessionApplicability[];
|
|
188
|
+
/** Fields a caller supplies for the session's census row. */
|
|
189
|
+
export interface ApplicabilityCensusInput {
|
|
190
|
+
taskChars: number;
|
|
191
|
+
evaluated: number;
|
|
192
|
+
undeclared: string[];
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* Append the session's census row. Best-effort like every other writer here: a
|
|
196
|
+
* false return means the line did not land, never a thrown turn.
|
|
197
|
+
*/
|
|
198
|
+
export declare function recordApplicabilityCensus(ctx: ExtensionContext, census: ApplicabilityCensusInput, storePath?: string): boolean;
|
|
199
|
+
/**
|
|
200
|
+
* Append one skill's verdict row. The same function writes the `read` upgrade:
|
|
201
|
+
* the fold decides, so no line is ever rewritten.
|
|
202
|
+
*/
|
|
203
|
+
export declare function recordApplicabilityVerdict(ctx: ExtensionContext, verdict: {
|
|
204
|
+
skill: string;
|
|
205
|
+
applicability: "read" | "ignored";
|
|
206
|
+
evidence: ApplicabilityEvidence[];
|
|
207
|
+
}, storePath?: string): boolean;
|
|
208
|
+
/**
|
|
209
|
+
* The folded applicability record for the context's own session, or undefined
|
|
210
|
+
* when the session wrote none. Reader: a refused path or a torn store is a
|
|
211
|
+
* miss, not a throw.
|
|
212
|
+
*/
|
|
213
|
+
export declare function getSessionApplicability(ctx: ExtensionContext, options?: {
|
|
214
|
+
storePath?: string;
|
|
215
|
+
}): SessionApplicability | undefined;
|
|
216
|
+
/**
|
|
217
|
+
* One skill's legs in one session: what the instrument saw happen to the body
|
|
218
|
+
* an obligation names.
|
|
219
|
+
*
|
|
220
|
+
* These are facts about reads and calls, not verdicts. `read` here means a
|
|
221
|
+
* DETECTED SKILL.md read, and it is deliberately not the applicability record's
|
|
222
|
+
* `applicability: "read"` class — that one is a verdict about a skill whose
|
|
223
|
+
* declared condition held, and the applicability record refuses to classify a
|
|
224
|
+
* read whose condition never held. This record states the read and leaves the
|
|
225
|
+
* verdict where it belongs.
|
|
226
|
+
*
|
|
227
|
+
* `called` and `applied` are the applied leg, and they are the reason the
|
|
228
|
+
* record exists:
|
|
229
|
+
* called a tool call in a family this skill declares happened this
|
|
230
|
+
* session, whatever the call's outcome — a refusal fires before the
|
|
231
|
+
* call and cannot know the result.
|
|
232
|
+
* applied the FIRST such call came after a detected read of this body.
|
|
233
|
+
*
|
|
234
|
+
* The pair is decided once, at the first call, because that is the only moment
|
|
235
|
+
* the ordering exists: a later read followed by a later call must not turn an
|
|
236
|
+
* earlier violation into satisfaction. Both stay false when the skill declares
|
|
237
|
+
* no family; most declare none, and an obligation that names no family is
|
|
238
|
+
* satisfied by the read alone.
|
|
239
|
+
*
|
|
240
|
+
* `suggested`, `listed` and `informed` are the surfaces that offered the body
|
|
241
|
+
* in this session (a delivered suggestion, a list_skills row, a delivered
|
|
242
|
+
* at-use line); they carry the "was it offered" half of adoption, which the
|
|
243
|
+
* call facts cannot.
|
|
244
|
+
*/
|
|
245
|
+
export interface ObligationLegRecord {
|
|
246
|
+
kind: "obligation";
|
|
247
|
+
sessionId: string;
|
|
248
|
+
role: string;
|
|
249
|
+
month: string;
|
|
250
|
+
updatedAt: string;
|
|
251
|
+
skill: string;
|
|
252
|
+
suggested: boolean;
|
|
253
|
+
listed: boolean;
|
|
254
|
+
/** An at-use inform was DELIVERED for this body in this session. */
|
|
255
|
+
informed: boolean;
|
|
256
|
+
read: boolean;
|
|
257
|
+
called: boolean;
|
|
258
|
+
applied: boolean;
|
|
259
|
+
}
|
|
260
|
+
/** A record's six legs, read back as one row per skill. */
|
|
261
|
+
export interface ObligationLegs {
|
|
262
|
+
skill: string;
|
|
263
|
+
suggested: boolean;
|
|
264
|
+
listed: boolean;
|
|
265
|
+
informed: boolean;
|
|
266
|
+
read: boolean;
|
|
267
|
+
called: boolean;
|
|
268
|
+
applied: boolean;
|
|
269
|
+
}
|
|
270
|
+
/** One session's obligation rows, folded. */
|
|
271
|
+
export interface SessionObligation {
|
|
272
|
+
sessionId: string;
|
|
273
|
+
role: string;
|
|
274
|
+
month: string;
|
|
275
|
+
updatedAt: string;
|
|
276
|
+
/** One row per skill seen, in first-seen order. */
|
|
277
|
+
skills: ObligationLegs[];
|
|
278
|
+
}
|
|
279
|
+
/** Normalize a parsed JSON line into an obligation record, or null. */
|
|
280
|
+
export declare function normalizeObligationRecord(raw: unknown): ObligationLegRecord | null;
|
|
281
|
+
/**
|
|
282
|
+
* Read the obligation records from the store. Missing or unreadable file →
|
|
283
|
+
* empty (never throws); other kinds and corrupt lines are skipped.
|
|
284
|
+
*/
|
|
285
|
+
export declare function readObligationRecords(storePath?: string): ObligationLegRecord[];
|
|
286
|
+
/**
|
|
287
|
+
* Fold a session's obligation rows into one record: the legs OR across every
|
|
288
|
+
* row, so a row that saw one leg never erases a leg a later row did not have.
|
|
289
|
+
* `called`/`applied` are written once per skill, so the OR is exact rather
|
|
290
|
+
* than convenient. A torn or duplicated row folds; a malformed one is dropped
|
|
291
|
+
* at normalize, before this sees it.
|
|
292
|
+
*/
|
|
293
|
+
export declare function foldObligationRecords(records: ObligationLegRecord[]): SessionObligation[];
|
|
294
|
+
/**
|
|
295
|
+
* Append one skill's legs. Best-effort like the sibling writer: a refused or
|
|
296
|
+
* missing store returns false so the caller can retry on a later turn.
|
|
297
|
+
*/
|
|
298
|
+
export declare function recordObligationLegs(ctx: ExtensionContext, legs: ObligationLegs, storePath?: string): boolean;
|
|
299
|
+
/** The current session's obligation rows, folded. Missing store → undefined. */
|
|
300
|
+
export declare function getSessionObligation(ctx: ExtensionContext, options?: {
|
|
301
|
+
storePath?: string;
|
|
302
|
+
}): SessionObligation | undefined;
|
|
303
|
+
/**
|
|
304
|
+
* An obligation is satisfied when the body was read AND, if the session ever
|
|
305
|
+
* called into a family the skill declares, that the first call came after the
|
|
306
|
+
* read. Without a declared family the second clause is vacuous: reading the
|
|
307
|
+
* body is the whole obligation.
|
|
308
|
+
*/
|
|
309
|
+
export declare function obligationSatisfied(legs: ObligationLegs): boolean;
|
|
310
|
+
/** One judged skill: its legs, plus whether it was even an obligation. */
|
|
311
|
+
export interface JudgedSkill extends ObligationLegs {
|
|
312
|
+
/** null when the skill's declared condition never held: no obligation. */
|
|
313
|
+
satisfied: boolean | null;
|
|
314
|
+
}
|
|
315
|
+
/** A session's judgement: every leg it recorded, and the session boolean. */
|
|
316
|
+
export interface SessionJudgement {
|
|
317
|
+
skills: JudgedSkill[];
|
|
318
|
+
allSatisfied: boolean;
|
|
319
|
+
/** Obligations that applied (leg rows whose condition held). */
|
|
320
|
+
obligations: number;
|
|
321
|
+
}
|
|
322
|
+
/**
|
|
323
|
+
* Judge one session against its obligation rows. Pure.
|
|
324
|
+
*
|
|
325
|
+
* A skill is an obligation when the applicability fold carries a verdict for
|
|
326
|
+
* it: the previous record's question was whether the skill applied, and this
|
|
327
|
+
* one takes that answer as given. An obligation is decided by this record's
|
|
328
|
+
* legs alone, which is why the two kinds can be folded independently and
|
|
329
|
+
* joined on (sessionId, skill) without either re-reading the other.
|
|
330
|
+
*/
|
|
331
|
+
export declare function judgeSessionObligations(applicable: SessionApplicability | undefined, obligation: SessionObligation | undefined): SessionJudgement | undefined;
|
|
332
|
+
/**
|
|
333
|
+
* The design's own decision rule: a gap this small makes the rate a duplicate
|
|
334
|
+
* of the read rate, and a duplicate should be deleted rather than shipped.
|
|
335
|
+
*/
|
|
336
|
+
export declare const FALSIFIER_GAP_POINTS = 5;
|
|
337
|
+
/**
|
|
338
|
+
* The two rates and their shared denominator.
|
|
339
|
+
*
|
|
340
|
+
* `sessions` is the population both rates are divided by: sessions with at
|
|
341
|
+
* least one obligation that applied AND at least one obligation row, i.e. the
|
|
342
|
+
* sessions this build's instrument saw. A session whose applicable verdicts
|
|
343
|
+
* predate the instrument is counted in `uninstrumented` instead of scored as
|
|
344
|
+
* unsatisfied — a zero the instrument did not observe is not a zero it found.
|
|
345
|
+
*
|
|
346
|
+
* `readRate` is the older measurement restricted to this population: a session
|
|
347
|
+
* counts when ANY detected read landed in it, which is the adoption counter's
|
|
348
|
+
* own definition (`actual > 0`), so the difference between the two numbers is
|
|
349
|
+
* the satisfaction criterion and nothing else.
|
|
350
|
+
*/
|
|
351
|
+
export interface ObligationRate {
|
|
352
|
+
sessions: number;
|
|
353
|
+
allSatisfied: number;
|
|
354
|
+
/** 0-1, rounded to 4 decimals (a percentage point is 2 of these). */
|
|
355
|
+
allSatisfiedRate: number;
|
|
356
|
+
withRead: number;
|
|
357
|
+
readRate: number;
|
|
358
|
+
/** allSatisfiedRate - readRate, in percentage points, 2 decimals. */
|
|
359
|
+
gapPoints: number;
|
|
360
|
+
/** Obligations that applied, across the population. */
|
|
361
|
+
obligations: number;
|
|
362
|
+
unsatisfied: number;
|
|
363
|
+
/** False when the gap is under FALSIFIER_GAP_POINTS: the metric is a copy. */
|
|
364
|
+
discriminating: boolean;
|
|
365
|
+
/** Sessions with an applicable skill but no obligation row: not scored. */
|
|
366
|
+
uninstrumented: number;
|
|
367
|
+
}
|
|
368
|
+
/** Compute both rates over one store's folds. Pure. */
|
|
369
|
+
export declare function computeObligationRate(sessions: SessionApplicability[], obligations: SessionObligation[]): ObligationRate;
|
|
370
|
+
/**
|
|
371
|
+
* The store-wide rate, or undefined when the store carries no obligation row
|
|
372
|
+
* at all. Undefined is the absent record: a reader of a store this build has
|
|
373
|
+
* not written to sees the payload it always saw, byte for byte.
|
|
374
|
+
*/
|
|
375
|
+
export declare function getObligationRate(options?: {
|
|
376
|
+
storePath?: string;
|
|
377
|
+
}): ObligationRate | undefined;
|
|
378
|
+
/**
|
|
379
|
+
* The suggestion channel's pair conversion as published from session-file
|
|
380
|
+
* mining: 95 read-followed pairs out of 506 delivered ones, Wilson 15.6-22.4.
|
|
381
|
+
*
|
|
382
|
+
* It is a measurement constant, not a target: it stands in as the comparison
|
|
383
|
+
* arm only while the same store carries too few suggested pairs of its own to
|
|
384
|
+
* stand on its own (see INFORM_DECISION_MIN_PAIRS). A two-pair store arm that
|
|
385
|
+
* happens to have converted nothing is not a baseline; it is a sample. The
|
|
386
|
+
* moment the store holds the floor of suggested pairs, their own fold answers
|
|
387
|
+
* and this number is not read.
|
|
388
|
+
*/
|
|
389
|
+
export declare const CHANNEL_PUBLISHED_CONVERSION = 0.188;
|
|
390
|
+
/** Wilson 95% bounds for that published figure, as proportions. */
|
|
391
|
+
export declare const CHANNEL_PUBLISHED_INTERVAL: WilsonInterval;
|
|
392
|
+
/**
|
|
393
|
+
* Informs needed before the comparison decides anything. Below this the
|
|
394
|
+
* answer is "undecided": a verdict from a handful of pairs would be a verdict
|
|
395
|
+
* about the sample, and the report's decision rule says so in writing before
|
|
396
|
+
* the first inform lands. The same floor governs the comparison arm: a store
|
|
397
|
+
* carrying fewer suggested pairs than this is not a baseline to beat.
|
|
398
|
+
*/
|
|
399
|
+
export declare const INFORM_DECISION_MIN_PAIRS = 20;
|
|
400
|
+
/** A two-sided interval on a proportion, both ends in 0-1. */
|
|
401
|
+
export interface WilsonInterval {
|
|
402
|
+
lower: number;
|
|
403
|
+
upper: number;
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* Wilson score interval for k successes in n trials (95% by default). Chosen
|
|
407
|
+
* over the normal approximation because the inform population is small and a
|
|
408
|
+
* small-sample interval is the only one that can say "undecided" honestly.
|
|
409
|
+
* Returns zeros for n = 0. Pure.
|
|
410
|
+
*/
|
|
411
|
+
export declare function wilsonInterval(successes: number, total: number, z?: number): WilsonInterval;
|
|
412
|
+
/** One skill's at-use pairs: informs delivered, and how many a read followed. */
|
|
413
|
+
export interface InformSkillRow {
|
|
414
|
+
skill: string;
|
|
415
|
+
informs: number;
|
|
416
|
+
readFollowed: number;
|
|
417
|
+
}
|
|
418
|
+
/** Where the comparison arm's number came from. */
|
|
419
|
+
export type ChannelBaselineSource = "store" | "published";
|
|
420
|
+
/**
|
|
421
|
+
* The at-use line's numbers beside the suggestion channel's, same store.
|
|
422
|
+
*
|
|
423
|
+
* A pair is (session, skill). An inform pair carries `informed: true`; it
|
|
424
|
+
* converted when that session also carries the `read` leg for the same skill.
|
|
425
|
+
* The read leg is ordered by construction here: a read silences the inform, so
|
|
426
|
+
* a pair that has both legs can only have read after the line landed.
|
|
427
|
+
*/
|
|
428
|
+
export interface InformRate {
|
|
429
|
+
/** Inform pairs in the store. */
|
|
430
|
+
informs: number;
|
|
431
|
+
/** Of those, pairs whose session carries the read leg. */
|
|
432
|
+
readFollowed: number;
|
|
433
|
+
/** readFollowed / informs, 4 decimals; 0 when no inform. */
|
|
434
|
+
conversion: number;
|
|
435
|
+
/** Wilson 95% bounds on `conversion`. */
|
|
436
|
+
ci: WilsonInterval;
|
|
437
|
+
/** Per skill, in first-seen order (only skills with an inform). */
|
|
438
|
+
skills: InformSkillRow[];
|
|
439
|
+
/** The comparison arm: the same fold's suggested pairs. */
|
|
440
|
+
channel: {
|
|
441
|
+
pairs: number;
|
|
442
|
+
readFollowed: number;
|
|
443
|
+
conversion: number;
|
|
444
|
+
ci: WilsonInterval;
|
|
445
|
+
source: ChannelBaselineSource;
|
|
446
|
+
};
|
|
447
|
+
/** conversion - channel.conversion, in percentage points, 2 decimals. */
|
|
448
|
+
gapPoints: number;
|
|
449
|
+
/** False below INFORM_DECISION_MIN_PAIRS: no verdict is derivable. */
|
|
450
|
+
decidable: boolean;
|
|
451
|
+
/** undecided | beats | noise (see the report's pre-registered rule). */
|
|
452
|
+
verdict: "undecided" | "beats" | "noise";
|
|
453
|
+
}
|
|
454
|
+
/**
|
|
455
|
+
* Fold the obligation rows into the at-use rate and the channel arm beside it.
|
|
456
|
+
* Pure.
|
|
457
|
+
*
|
|
458
|
+
* The rule, applied literally: fewer than the floor is undecided; at the floor
|
|
459
|
+
* the inform beats the channel only when its point estimate is above the
|
|
460
|
+
* channel's AND its lower Wilson bound is above it too. Anything else at the
|
|
461
|
+
* floor is noise, which is the falsifier firing rather than a neutral result.
|
|
462
|
+
*/
|
|
463
|
+
export declare function computeInformRate(obligations: SessionObligation[]): InformRate;
|
|
464
|
+
/**
|
|
465
|
+
* The store-wide at-use rate, or undefined when the store carries no inform row
|
|
466
|
+
* at all. Undefined keeps every existing `skill_stats` payload byte-identical
|
|
467
|
+
* for a build or an install that never emitted one.
|
|
468
|
+
*/
|
|
469
|
+
export declare function getInformRate(options?: {
|
|
470
|
+
storePath?: string;
|
|
471
|
+
}): InformRate | undefined;
|
|
85
472
|
/** Adoption numbers for one profile in one month. */
|
|
86
473
|
export interface ProfileAdoption {
|
|
87
474
|
/** Sessions active in the month (records with a turn). */
|