pi-braid 0.43.9 → 0.43.12
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 +48 -0
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/index.d.ts +11 -3
- package/dist/extensions/core/skills-tool/index.js +27 -3
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +2 -2
- package/dist/extensions/core/skills-tool/loading-guidance.js +2 -2
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +22 -0
- package/dist/extensions/core/skills-tool/skill-triggers.js +29 -4
- package/dist/lib/memory/decision-grammar.d.ts +94 -0
- package/dist/lib/memory/decision-grammar.js +348 -0
- package/dist/lib/memory/index.d.ts +1 -0
- package/dist/lib/memory/index.js +1 -0
- package/dist/lib/orchestrator/owner-speech.d.ts +114 -0
- package/dist/lib/orchestrator/owner-speech.js +234 -0
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +1 -0
- package/src/extensions/core/skills-tool/index.ts +34 -6
- package/src/extensions/core/skills-tool/loading-guidance.ts +2 -2
- package/src/extensions/core/skills-tool/skill-triggers.ts +43 -4
- package/src/lib/memory/decision-grammar.ts +405 -0
- package/src/lib/memory/index.ts +10 -0
- package/src/lib/orchestrator/owner-speech.ts +286 -0
package/CHANGELOG.md
CHANGED
|
@@ -53,6 +53,54 @@ record; the tag scheme above applies unchanged.
|
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
+
## Core — 0.43.12 (2026-11-01: a skill that says it is retired stops being advertised)
|
|
57
|
+
|
|
58
|
+
- **A retired skill no longer competes with its successor.** Four skills in the packs declare
|
|
59
|
+
`status: merged` and nothing read the declaration, so `code-search` was still listed beside
|
|
60
|
+
`code-refactoring` — two entries for one job, no sign which was current. A declared status of
|
|
61
|
+
`merged`, `archived` or `deprecated` now rides the exclusion the cache already had, so the catalog,
|
|
62
|
+
the suggestion whisper, the at-use line, both catalog accessors and `list_skills` agree without a
|
|
63
|
+
second concept. The file stays on disk and an explicit read of it still resolves: the skill stops
|
|
64
|
+
being advertised, it does not become unreadable. The status comes from the frontmatter parse the
|
|
65
|
+
trigger phrases already paid for, so no skill file is read a third time.
|
|
66
|
+
- **The budget gate it disturbed now tests the rule rather than its own reflection.** One existing
|
|
67
|
+
measurement asserted that every skill in the pack appears in one catalog page; with a retired skill
|
|
68
|
+
legitimately absent, the writer's first repair compared the page to the module's own accessor, which
|
|
69
|
+
is the same code on both sides and cannot catch a _wrong_ exclusion. The assertion instead derives the
|
|
70
|
+
expected population from the SKILL.md files themselves, so a skill retired for no reason in its
|
|
71
|
+
frontmatter reddens the gate. The seat verified that by planting one.
|
|
72
|
+
|
|
73
|
+
## Core — 0.43.11 (2026-11-01: an owner ruling becomes findable, and the pointer rule stops licensing the skip)
|
|
74
|
+
|
|
75
|
+
- **The pointer rule no longer licenses skipping the read.** The sentence it carried — `The prompt already
|
|
76
|
+
covering the domain is the only reason to skip the read` — named the wrong test: a prompt that covers a
|
|
77
|
+
domain carries a description, a catalog line or an excerpt, and the body is what the agent is supposed
|
|
78
|
+
to read. So it authorised skipping in precisely the case where a summary and the body part company, and
|
|
79
|
+
it called that the _only_ reason, denying the legitimate one. It now reads `If the body itself is
|
|
80
|
+
already in this prompt you have read it; if you have only a description or an excerpt, you have not.` A
|
|
81
|
+
new fixture asserts this against the assembled prompt, reddens on three planted licences including the
|
|
82
|
+
retired sentence, and re-runs the whole check against a rebuilt copy of the module with the old
|
|
83
|
+
sentence restored. The behavioural effect is unmeasured and the report says so: this subsystem's claims
|
|
84
|
+
are structural until a probe with a control arm runs.
|
|
85
|
+
- **Owner rulings are filed where recall can reach them, and split by layer.** A backfill reads the
|
|
86
|
+
session corpus, decides which user turns are the owner stating a standing instruction, and writes each
|
|
87
|
+
one into the semantic store with a pointer that re-reads the original transcript line. The classifier
|
|
88
|
+
is split along the line the placement gate draws: the generic decision grammar stays in the memory
|
|
89
|
+
layer, and everything braid-shaped — whisper envelopes, a seat's dispatch anatomy, pasted-brief
|
|
90
|
+
headings, session machinery, role vocabulary — lives in the orchestration domain layer that already
|
|
91
|
+
owns those words. A generic layer holding them is what refused this work the first time, at nine
|
|
92
|
+
literal hits with the exclusion budget full.
|
|
93
|
+
- **A ruling's tags are derived from the store, because a flat bonus does not pay for rarity.** A
|
|
94
|
+
pre-registered measurement over ten questions found only three reachable answers and reached two of
|
|
95
|
+
them. The rule that did it is the opposite of the intuition: a tag's bonus is a constant, so how rare a
|
|
96
|
+
token is buys the entry nothing, and the only property worth maximising is whether a later question
|
|
97
|
+
names it — which is what store frequency measures. Measured against five control entries, both
|
|
98
|
+
reachable questions then hold rank one. The price is stated rather than hidden: across the twenty
|
|
99
|
+
questions that have an answer in the store, non-expected rulings appear in the top five 33 times
|
|
100
|
+
against 25 before, because a common tag fires on more queries. Four provenance scoring policies were
|
|
101
|
+
then measured as a replacement and none pays: they are inert on this store, and the one shape that
|
|
102
|
+
bites costs more noise and still leaves the target at rank two.
|
|
103
|
+
|
|
56
104
|
## Core — 0.43.9 (2026-10-31: a query is read as tokens, and the store can be told what to keep)
|
|
57
105
|
|
|
58
106
|
- **A question could not match a word it contained.** Recall split a query on whitespace alone, so a
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.12",
|
|
4
|
+
"sha": "f6a311a974d34f1d7cc70a491a8f5544e85dd233",
|
|
5
|
+
"shaShort": "f6a311a9",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-
|
|
8
|
+
"packedAt": "2026-11-01T08:52:31.302Z"
|
|
9
9
|
}
|
|
@@ -45,9 +45,10 @@ interface CachedSkill {
|
|
|
45
45
|
package?: string;
|
|
46
46
|
};
|
|
47
47
|
/**
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
48
|
+
* Excluded from model selection: pi's own frontmatter flag, or a status this
|
|
49
|
+
* cache reads as retired (see RETIRED_STATUSES). Either way braid keeps the
|
|
50
|
+
* skill out of the surfaces that advertise skills to the model, while the
|
|
51
|
+
* file stays on disk and an explicit read of it still resolves.
|
|
51
52
|
*/
|
|
52
53
|
disableModelInvocation?: boolean;
|
|
53
54
|
/** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
|
|
@@ -60,6 +61,13 @@ interface CachedSkill {
|
|
|
60
61
|
* Resolves each skill's frontmatter trigger phrases here, once per turn:
|
|
61
62
|
* the matcher scores triggers, pi's skill objects never carry them (fixed
|
|
62
63
|
* shape), and the memoized read makes repeat turns stat-only.
|
|
64
|
+
*
|
|
65
|
+
* The same read answers the file's `status:`, and a retired status rides the
|
|
66
|
+
* `disableModelInvocation` exclusion rather than a second one: every surface
|
|
67
|
+
* that advertises skills already filters on that flag, so one derived field
|
|
68
|
+
* keeps the catalog, the whisper, the at-use line and the accessors in
|
|
69
|
+
* agreement. The row is still cached, so an explicit read of the file is still
|
|
70
|
+
* recognized — the skill stops being advertised, not becoming unreadable.
|
|
63
71
|
*/
|
|
64
72
|
export declare function setCachedSkills(skills: CachedSkill[]): void;
|
|
65
73
|
/**
|
|
@@ -35,25 +35,47 @@ import { Type } from "typebox";
|
|
|
35
35
|
import { createLogger } from "../../../lib/core/logger.js";
|
|
36
36
|
import { getSkillsInformMode, getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
37
37
|
import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, noteObligationListed, resolveDiscoveryMode, rankSkillsDeterministic, } from "./auto-inject.js";
|
|
38
|
-
import {
|
|
38
|
+
import { readSkillFrontmatter } from "./skill-triggers.js";
|
|
39
39
|
import { readGovernedFamilies } from "./skill-families.js";
|
|
40
40
|
import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
|
|
41
41
|
import { getInformRate, getMonthlyAdoptionRollup, getObligationRate, getSessionApplicability, getSessionObligation, judgeSessionObligations, } from "./session-records.js";
|
|
42
42
|
import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
|
|
43
43
|
const log = createLogger("skills-tool");
|
|
44
44
|
let cachedSkills = [];
|
|
45
|
+
/**
|
|
46
|
+
* Statuses that mean the skill is no longer the place to look: its content
|
|
47
|
+
* lives in a successor, or the file is kept as history. The vocabulary is the
|
|
48
|
+
* pack's (a `status:` frontmatter key), and the exclusion is this module's:
|
|
49
|
+
* no file is deleted, renamed or edited to make a skill stop being advertised.
|
|
50
|
+
*/
|
|
51
|
+
const RETIRED_STATUSES = new Set(["merged", "archived", "deprecated"]);
|
|
52
|
+
/** Whether a declared status retires the skill from model selection. */
|
|
53
|
+
function isRetiredStatus(status) {
|
|
54
|
+
return RETIRED_STATUSES.has(status);
|
|
55
|
+
}
|
|
45
56
|
/**
|
|
46
57
|
* Called from prompt-builder's before_agent_start to populate the cache.
|
|
47
58
|
* Resolves each skill's frontmatter trigger phrases here, once per turn:
|
|
48
59
|
* the matcher scores triggers, pi's skill objects never carry them (fixed
|
|
49
60
|
* shape), and the memoized read makes repeat turns stat-only.
|
|
61
|
+
*
|
|
62
|
+
* The same read answers the file's `status:`, and a retired status rides the
|
|
63
|
+
* `disableModelInvocation` exclusion rather than a second one: every surface
|
|
64
|
+
* that advertises skills already filters on that flag, so one derived field
|
|
65
|
+
* keeps the catalog, the whisper, the at-use line and the accessors in
|
|
66
|
+
* agreement. The row is still cached, so an explicit read of the file is still
|
|
67
|
+
* recognized — the skill stops being advertised, not becoming unreadable.
|
|
50
68
|
*/
|
|
51
69
|
export function setCachedSkills(skills) {
|
|
70
|
+
let retired = 0;
|
|
52
71
|
cachedSkills = skills.map((s) => {
|
|
53
|
-
const entries =
|
|
72
|
+
const { entries, status } = readSkillFrontmatter(s.filePath, s.description);
|
|
54
73
|
const triggerSources = {};
|
|
55
74
|
for (const entry of entries)
|
|
56
75
|
triggerSources[entry.phrase] = entry.source;
|
|
76
|
+
const isRetired = isRetiredStatus(status);
|
|
77
|
+
if (isRetired)
|
|
78
|
+
retired++;
|
|
57
79
|
return {
|
|
58
80
|
...s,
|
|
59
81
|
triggers: entries.map((entry) => entry.phrase),
|
|
@@ -62,11 +84,13 @@ export function setCachedSkills(skills) {
|
|
|
62
84
|
// frontmatter read the phrases come from (one extra parse per file per
|
|
63
85
|
// process). An empty list is a declaration of no family, not a miss.
|
|
64
86
|
families: readGovernedFamilies(s.filePath),
|
|
87
|
+
disableModelInvocation: s.disableModelInvocation === true || isRetired,
|
|
65
88
|
};
|
|
66
89
|
});
|
|
67
90
|
// Sync with auto-inject subsystem (enriched cache — triggers ride along)
|
|
68
91
|
updateSkillCache(cachedSkills);
|
|
69
|
-
log.debug(`Cached ${skills.length} skills for list_skills tool`
|
|
92
|
+
log.debug(`Cached ${skills.length} skills for list_skills tool` +
|
|
93
|
+
(retired ? ` (${retired} retired by status)` : ""));
|
|
70
94
|
}
|
|
71
95
|
/**
|
|
72
96
|
* The installed visible skill names — the same set the list_skills catalog
|
|
@@ -51,8 +51,8 @@ export interface CatalogEntry {
|
|
|
51
51
|
* the honest answer when the paths cannot be derived.
|
|
52
52
|
*/
|
|
53
53
|
export declare function skillsCatalogRule(readRoot: string, grouped?: boolean): string;
|
|
54
|
-
/** Paragraph 2: the pointer rule
|
|
55
|
-
export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge.
|
|
54
|
+
/** Paragraph 2: the pointer rule, exported so a fixture can pin its text. */
|
|
55
|
+
export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge. If the body itself is already in this prompt you have read it; if you have only a description or an excerpt, you have not.";
|
|
56
56
|
/** One directory a catalog's bodies live in, with the skills filed under it. */
|
|
57
57
|
export interface CatalogGroup {
|
|
58
58
|
/** The pack directory itself, in forward-slash form. */
|
|
@@ -54,8 +54,8 @@ export function skillsCatalogRule(readRoot, grouped = false) {
|
|
|
54
54
|
: "";
|
|
55
55
|
return `This catalog is every installed skill: one row per skill, name and description.${readPath} When the task enters a listed skill's domain, read the WHOLE SKILL.md before acting in that domain; never act from memory of a skill's contents.`;
|
|
56
56
|
}
|
|
57
|
-
/** Paragraph 2: the pointer rule
|
|
58
|
-
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge.
|
|
57
|
+
/** Paragraph 2: the pointer rule, exported so a fixture can pin its text. */
|
|
58
|
+
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge. If the body itself is already in this prompt you have read it; if you have only a description or an excerpt, you have not.`;
|
|
59
59
|
const MECHANICAL_TRIGGER_LEAD = `Mechanical trigger, no judgment call: about to use a tool family whose word appears in a skill's name`;
|
|
60
60
|
const MECHANICAL_TRIGGER_TAIL = `→ read that SKILL.md before the first call in the family.`;
|
|
61
61
|
/** Forward-slash form of a path, for segment arithmetic on either platform. */
|
|
@@ -28,6 +28,12 @@
|
|
|
28
28
|
* capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
|
|
29
29
|
* lowercase text would be dead in production while a lowercase-only unit
|
|
30
30
|
* fixture kept the suite green.
|
|
31
|
+
*
|
|
32
|
+
* The same parse also returns the file's declared lifecycle `status`, which is
|
|
33
|
+
* NOT matcher input: the skills-tool needs it once per file, at cache time, to
|
|
34
|
+
* decide whether the skill is still advertised. It rides this read because the
|
|
35
|
+
* file is already open here — a reader of its own would be a third read of the
|
|
36
|
+
* same bytes per process, and a status is not worth one.
|
|
31
37
|
*/
|
|
32
38
|
/**
|
|
33
39
|
* Max trigger phrases read per skill — a longer list is an authoring bug, not a
|
|
@@ -51,6 +57,15 @@ export interface TriggerEntry {
|
|
|
51
57
|
phrase: string;
|
|
52
58
|
source: TriggerSource;
|
|
53
59
|
}
|
|
60
|
+
/**
|
|
61
|
+
* One SKILL.md's trigger phrases plus the lifecycle status its frontmatter
|
|
62
|
+
* declares — everything one parse of the file answers.
|
|
63
|
+
*/
|
|
64
|
+
export interface SkillFrontmatterRead {
|
|
65
|
+
entries: TriggerEntry[];
|
|
66
|
+
/** Lowercased `status:` token, or "" when the file declares none. */
|
|
67
|
+
status: string;
|
|
68
|
+
}
|
|
54
69
|
/**
|
|
55
70
|
* Normalize a frontmatter `triggers` value into clean phrases. Accepts a YAML
|
|
56
71
|
* list or a comma-separated string; drops empty, overlong, and surplus
|
|
@@ -76,6 +91,13 @@ export declare function readSkillTriggers(filePath: string, description?: string
|
|
|
76
91
|
* a miss, because the merged list depends on it).
|
|
77
92
|
*/
|
|
78
93
|
export declare function readSkillTriggerEntries(filePath: string, description?: string): TriggerEntry[];
|
|
94
|
+
/**
|
|
95
|
+
* Read a skill's trigger phrases WITH their provenance plus its declared
|
|
96
|
+
* lifecycle status, from one memoized parse. Same sources, precedence and
|
|
97
|
+
* memoization as readSkillTriggerEntries; the status is the frontmatter key of
|
|
98
|
+
* that name, lowercased, "" when absent or unreadable.
|
|
99
|
+
*/
|
|
100
|
+
export declare function readSkillFrontmatter(filePath: string, description?: string): SkillFrontmatterRead;
|
|
79
101
|
/**
|
|
80
102
|
* Merge authored phrase sources into one bounded list, in priority order.
|
|
81
103
|
*
|
|
@@ -28,6 +28,12 @@
|
|
|
28
28
|
* capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
|
|
29
29
|
* lowercase text would be dead in production while a lowercase-only unit
|
|
30
30
|
* fixture kept the suite green.
|
|
31
|
+
*
|
|
32
|
+
* The same parse also returns the file's declared lifecycle `status`, which is
|
|
33
|
+
* NOT matcher input: the skills-tool needs it once per file, at cache time, to
|
|
34
|
+
* decide whether the skill is still advertised. It rides this read because the
|
|
35
|
+
* file is already open here — a reader of its own would be a third read of the
|
|
36
|
+
* same bytes per process, and a status is not worth one.
|
|
31
37
|
*/
|
|
32
38
|
import { statSync, readFileSync } from "node:fs";
|
|
33
39
|
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
@@ -76,6 +82,14 @@ export function normalizeTriggers(value) {
|
|
|
76
82
|
export function readSkillTriggers(filePath, description) {
|
|
77
83
|
return readSkillTriggerEntries(filePath, description).map((entry) => entry.phrase);
|
|
78
84
|
}
|
|
85
|
+
/**
|
|
86
|
+
* Normalize a frontmatter `status` value into the token a caller matches on.
|
|
87
|
+
* Only a string is a declaration: a missing key, a null, or a nested shape is
|
|
88
|
+
* the absence of one. Pure.
|
|
89
|
+
*/
|
|
90
|
+
function normalizeSkillStatus(value) {
|
|
91
|
+
return typeof value === "string" ? value.trim().toLowerCase() : "";
|
|
92
|
+
}
|
|
79
93
|
/**
|
|
80
94
|
* Read a skill's authored phrases WITH their provenance, merged in priority
|
|
81
95
|
* order: frontmatter (`trigger` or `triggers`), then a `## trigger:` body
|
|
@@ -86,6 +100,15 @@ export function readSkillTriggers(filePath, description) {
|
|
|
86
100
|
* a miss, because the merged list depends on it).
|
|
87
101
|
*/
|
|
88
102
|
export function readSkillTriggerEntries(filePath, description) {
|
|
103
|
+
return readSkillFrontmatter(filePath, description).entries;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Read a skill's trigger phrases WITH their provenance plus its declared
|
|
107
|
+
* lifecycle status, from one memoized parse. Same sources, precedence and
|
|
108
|
+
* memoization as readSkillTriggerEntries; the status is the frontmatter key of
|
|
109
|
+
* that name, lowercased, "" when absent or unreadable.
|
|
110
|
+
*/
|
|
111
|
+
export function readSkillFrontmatter(filePath, description) {
|
|
89
112
|
const desc = description ?? "";
|
|
90
113
|
let st;
|
|
91
114
|
try {
|
|
@@ -93,20 +116,22 @@ export function readSkillTriggerEntries(filePath, description) {
|
|
|
93
116
|
}
|
|
94
117
|
catch {
|
|
95
118
|
cache.delete(filePath);
|
|
96
|
-
return [];
|
|
119
|
+
return { entries: [], status: "" };
|
|
97
120
|
}
|
|
98
121
|
const cached = cache.get(filePath);
|
|
99
122
|
if (cached &&
|
|
100
123
|
cached.mtimeMs === st.mtimeMs &&
|
|
101
124
|
cached.size === st.size &&
|
|
102
125
|
cached.description === desc) {
|
|
103
|
-
return cached.entries;
|
|
126
|
+
return { entries: cached.entries, status: cached.status };
|
|
104
127
|
}
|
|
105
128
|
const sources = [];
|
|
129
|
+
let status = "";
|
|
106
130
|
try {
|
|
107
131
|
const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
108
132
|
const fm = frontmatter;
|
|
109
133
|
const label = (source) => (phrase) => ({ phrase, source });
|
|
134
|
+
status = normalizeSkillStatus(fm.status);
|
|
110
135
|
sources.push(normalizeTriggers(fm.trigger).map(label("frontmatter")), normalizeTriggers(fm.triggers).map(label("frontmatter")), parseBodyTriggers(body).map(label("heading")));
|
|
111
136
|
}
|
|
112
137
|
catch {
|
|
@@ -116,8 +141,8 @@ export function readSkillTriggerEntries(filePath, description) {
|
|
|
116
141
|
if (desc)
|
|
117
142
|
sources.push(parseDescriptionTriggers(desc).map((phrase) => ({ phrase, source: "description" })));
|
|
118
143
|
const entries = mergeTriggerEntries(sources);
|
|
119
|
-
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries });
|
|
120
|
-
return entries;
|
|
144
|
+
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries, status });
|
|
145
|
+
return { entries, status };
|
|
121
146
|
}
|
|
122
147
|
/**
|
|
123
148
|
* Merge authored phrase sources into one bounded list, in priority order.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Decision grammar: the generic half of the ruling write path.
|
|
3
|
+
*
|
|
4
|
+
* One body of text in, either the standing instruction it carries or `null`.
|
|
5
|
+
* "Generic" is a claim about what the module is allowed to know: sentence
|
|
6
|
+
* spans, the marker table that turns a sentence into a standing instruction,
|
|
7
|
+
* the shapes that are not instructions (a question, a status report, a paste, a
|
|
8
|
+
* hedge, a conversational aside), and the first- and second-person grammar of
|
|
9
|
+
* English. It knows nothing about who wrote the text, which channel carried it,
|
|
10
|
+
* or what the caller's world is made of.
|
|
11
|
+
*
|
|
12
|
+
* The last of those is the one thing a grammar cannot supply, so the caller
|
|
13
|
+
* hands it in as `GrammarVocabulary`: which words name a subject a ruling can be
|
|
14
|
+
* about, which words describe the caller's own machinery, and how an explicit
|
|
15
|
+
* generalization reads. `classifyRulingBody()` applies those three tests at the
|
|
16
|
+
* same two places it applies its own - the turn and the sentence that gets
|
|
17
|
+
* quoted - so a directive aimed at the reader is told apart from a rule about
|
|
18
|
+
* the system by vocabulary this layer never spells.
|
|
19
|
+
*
|
|
20
|
+
* The second half of the module is the store side of the same write path:
|
|
21
|
+
* `deriveTopicTags()` reads a quote and the population it is filed into and
|
|
22
|
+
* returns the words worth carrying as tags. The rule reasons about tokens,
|
|
23
|
+
* document frequency and a generic English stop list, so it belongs next to the
|
|
24
|
+
* grammar rather than in the caller's vocabulary.
|
|
25
|
+
*
|
|
26
|
+
* Pure by construction: no I/O, no clock, no randomness, so its behaviour is a
|
|
27
|
+
* fixture instead of a story.
|
|
28
|
+
*/
|
|
29
|
+
/** The closed set of ruling shapes the classifier can name. */
|
|
30
|
+
export type RulingClass = "prohibition" | "preference" | "requirement" | "policy";
|
|
31
|
+
/** A classified body: what kind of instruction it is, and the words to keep. */
|
|
32
|
+
export interface RulingShape {
|
|
33
|
+
class: RulingClass;
|
|
34
|
+
/** A contiguous, verbatim slice of the body, capped with a trailing ellipsis. */
|
|
35
|
+
quote: string;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* The three questions a grammar has to ask the caller's world.
|
|
39
|
+
*
|
|
40
|
+
* `namesSubject` is the escape hatch for a bare directive: "Do not read or
|
|
41
|
+
* write files." names no system, so without first person it is an instruction
|
|
42
|
+
* aimed at the reader, not a rule about anything. `talksProcess` refuses a body
|
|
43
|
+
* whose subject is the caller's own machinery rather than the thing a ruling is
|
|
44
|
+
* about, and `generalizes` admits a second-person body that says it speaks to
|
|
45
|
+
* every recipient ("any instance", "generically"), which is a rule rather than
|
|
46
|
+
* a steer.
|
|
47
|
+
*/
|
|
48
|
+
export interface GrammarVocabulary {
|
|
49
|
+
namesSubject(text: string): boolean;
|
|
50
|
+
talksProcess(text: string): boolean;
|
|
51
|
+
generalizes(text: string): boolean;
|
|
52
|
+
}
|
|
53
|
+
/** Longest quote the caller receives; past this the quote is cut, not summarized. */
|
|
54
|
+
export declare const QUOTE_LIMIT = 400;
|
|
55
|
+
/**
|
|
56
|
+
* Classify one body that is already known to be owner speech.
|
|
57
|
+
*
|
|
58
|
+
* Returns `null` for everything that is not a standing instruction: a question,
|
|
59
|
+
* a paste, a status report, a hedged recommendation, an acknowledgement, a
|
|
60
|
+
* second-person directive, or a body too long to cut a self-contained sentence
|
|
61
|
+
* from. Returns the class and the verbatim quote otherwise. The caller owns the
|
|
62
|
+
* provenance fields, because the caller is the one that knows where the text
|
|
63
|
+
* came from.
|
|
64
|
+
*/
|
|
65
|
+
export declare function classifyRulingBody(text: string, vocabulary: GrammarVocabulary): RulingShape | null;
|
|
66
|
+
/** How many tags a ruling carries. */
|
|
67
|
+
export declare const TAG_LIMIT = 3;
|
|
68
|
+
/**
|
|
69
|
+
* The population a quote is filed into, as the frequency test sees it:
|
|
70
|
+
* how many documents it holds, and how many of them carry a token.
|
|
71
|
+
*/
|
|
72
|
+
export interface TagPopulation {
|
|
73
|
+
/** Documents in the population. */
|
|
74
|
+
total: number;
|
|
75
|
+
/** Documents carrying `token`. */
|
|
76
|
+
count(token: string): number;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* The tags a quote earns from the population it is filed into.
|
|
80
|
+
*
|
|
81
|
+
* Take the quote's tokens of four characters or more, drop the read path's stop
|
|
82
|
+
* words, drop any token more than a quarter of the population carries, and keep
|
|
83
|
+
* the three the population carries most, ties by first occurrence.
|
|
84
|
+
*
|
|
85
|
+
* The ranking is by frequency and not by rarity, and the reason is the read
|
|
86
|
+
* path's own arithmetic: a tag's bonus is a flat constant however rare the
|
|
87
|
+
* token is, so rarity buys nothing a later query will say. Two tokens of equal
|
|
88
|
+
* rarity are worth the same as tags, and the one a question is likelier to name
|
|
89
|
+
* is the one the population's own prose uses more often. That makes the
|
|
90
|
+
* frequency ranking the findability ranking, and it leaves the 25% cap as the
|
|
91
|
+
* only guard against a tag that names nothing.
|
|
92
|
+
*/
|
|
93
|
+
export declare function deriveTopicTags(text: string, population: TagPopulation, limit?: number): string[];
|
|
94
|
+
//# sourceMappingURL=decision-grammar.d.ts.map
|