pi-braid 0.43.9 → 0.43.11
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 +31 -0
- package/build-info.json +4 -4
- 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/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/skills-tool/loading-guidance.ts +2 -2
- 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,37 @@ record; the tag scheme above applies unchanged.
|
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
+
## Core — 0.43.11 (2026-11-01: an owner ruling becomes findable, and the pointer rule stops licensing the skip)
|
|
57
|
+
|
|
58
|
+
- **The pointer rule no longer licenses skipping the read.** The sentence it carried — `The prompt already
|
|
59
|
+
covering the domain is the only reason to skip the read` — named the wrong test: a prompt that covers a
|
|
60
|
+
domain carries a description, a catalog line or an excerpt, and the body is what the agent is supposed
|
|
61
|
+
to read. So it authorised skipping in precisely the case where a summary and the body part company, and
|
|
62
|
+
it called that the _only_ reason, denying the legitimate one. It now reads `If the body itself is
|
|
63
|
+
already in this prompt you have read it; if you have only a description or an excerpt, you have not.` A
|
|
64
|
+
new fixture asserts this against the assembled prompt, reddens on three planted licences including the
|
|
65
|
+
retired sentence, and re-runs the whole check against a rebuilt copy of the module with the old
|
|
66
|
+
sentence restored. The behavioural effect is unmeasured and the report says so: this subsystem's claims
|
|
67
|
+
are structural until a probe with a control arm runs.
|
|
68
|
+
- **Owner rulings are filed where recall can reach them, and split by layer.** A backfill reads the
|
|
69
|
+
session corpus, decides which user turns are the owner stating a standing instruction, and writes each
|
|
70
|
+
one into the semantic store with a pointer that re-reads the original transcript line. The classifier
|
|
71
|
+
is split along the line the placement gate draws: the generic decision grammar stays in the memory
|
|
72
|
+
layer, and everything braid-shaped — whisper envelopes, a seat's dispatch anatomy, pasted-brief
|
|
73
|
+
headings, session machinery, role vocabulary — lives in the orchestration domain layer that already
|
|
74
|
+
owns those words. A generic layer holding them is what refused this work the first time, at nine
|
|
75
|
+
literal hits with the exclusion budget full.
|
|
76
|
+
- **A ruling's tags are derived from the store, because a flat bonus does not pay for rarity.** A
|
|
77
|
+
pre-registered measurement over ten questions found only three reachable answers and reached two of
|
|
78
|
+
them. The rule that did it is the opposite of the intuition: a tag's bonus is a constant, so how rare a
|
|
79
|
+
token is buys the entry nothing, and the only property worth maximising is whether a later question
|
|
80
|
+
names it — which is what store frequency measures. Measured against five control entries, both
|
|
81
|
+
reachable questions then hold rank one. The price is stated rather than hidden: across the twenty
|
|
82
|
+
questions that have an answer in the store, non-expected rulings appear in the top five 33 times
|
|
83
|
+
against 25 before, because a common tag fires on more queries. Four provenance scoring policies were
|
|
84
|
+
then measured as a replacement and none pays: they are inert on this store, and the one shape that
|
|
85
|
+
bites costs more noise and still leaves the target at rank two.
|
|
86
|
+
|
|
56
87
|
## Core — 0.43.9 (2026-10-31: a query is read as tokens, and the store can be told what to keep)
|
|
57
88
|
|
|
58
89
|
- **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.11",
|
|
4
|
+
"sha": "078bb68b180cfc69cc2cb796ddc2a75365b731c1",
|
|
5
|
+
"shaShort": "078bb68b",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-
|
|
8
|
+
"packedAt": "2026-11-01T07:47:23.285Z"
|
|
9
9
|
}
|
|
@@ -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. */
|
|
@@ -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
|
|
@@ -0,0 +1,348 @@
|
|
|
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
|
+
import { QUERY_STOP_WORDS } from "./constants.js";
|
|
30
|
+
/** Longest quote the caller receives; past this the quote is cut, not summarized. */
|
|
31
|
+
export const QUOTE_LIMIT = 400;
|
|
32
|
+
/**
|
|
33
|
+
* A body longer than this is a pasted brief, a log or a tool dump, not the
|
|
34
|
+
* sentence an owner states a ruling in. The quote is capped at QUOTE_LIMIT
|
|
35
|
+
* anyway, so a long body can only contribute a fragment whose subject was three
|
|
36
|
+
* paragraphs earlier.
|
|
37
|
+
*/
|
|
38
|
+
const MAX_TURN_CHARS = 1200;
|
|
39
|
+
/** Below this a body is an acknowledgement ("ok", "proceed"), never a ruling. */
|
|
40
|
+
const MIN_TURN_WORDS = 3;
|
|
41
|
+
/** A continuation sentence is kept only while the quote stays short enough to read. */
|
|
42
|
+
const CONTINUATION_LIMIT = 200;
|
|
43
|
+
/** The owner's own voice: first person, singular or collective. */
|
|
44
|
+
const FIRST_PERSON = /\b(?:i|i'm|i've|i'll|i'd|we|we're|we've|we'll|we'd|my|our|ours|let's)\b/i;
|
|
45
|
+
/**
|
|
46
|
+
* Second-person address. A directive written to *you* is an instruction for
|
|
47
|
+
* the reader; a rule for the system talks about it, or generalizes explicitly.
|
|
48
|
+
*/
|
|
49
|
+
const SECOND_PERSON = /\b(?:you|your|yours|yourself|yourselves)\b/i;
|
|
50
|
+
/**
|
|
51
|
+
* First-person report voice: the speaker narrating what was seen, changed or
|
|
52
|
+
* disabled. Such a sentence can carry "always" or "no longer" by accident ("I
|
|
53
|
+
* still see only ...", "it no longer indexed"), so it is refused unless it opens
|
|
54
|
+
* with a directive.
|
|
55
|
+
*/
|
|
56
|
+
const REPORT_VOICE = /\b(?:i|we)\b[^.!?]{0,120}\b(?:noticed|noticing|see|saw|seen|disabled|enabled|changed|updated|merged|pushed|committed|created|deleted|found|think|thought|guess|believe|realised|realized|checked|ran|built|fixed|added|removed|renamed|replaced|read|told|said|mentioned)\b/i;
|
|
57
|
+
/**
|
|
58
|
+
* Conversational openers that carry no decision: thinking aloud. A marker
|
|
59
|
+
* inside one of these ("doesn't really matter") is not a ruling.
|
|
60
|
+
*/
|
|
61
|
+
const CONVERSATIONAL = /^\s*(?:or i don'?t know|i don'?t know|not sure|doesn'?t really matter|whatever|never mind|nevermind)\b/i;
|
|
62
|
+
/** A body that reads as a report of work already done, on its first line. */
|
|
63
|
+
const STATUS_OPENER = /^(?:done|finished|merged|shipped|pushed|committed|built|fixed|updated|completed|released|deployed|landed|green|all (?:tests|gates|checks)|tests? (?:pass|green)|gates? (?:pass|green))/i;
|
|
64
|
+
/**
|
|
65
|
+
* Hedged advice: the shape of a recommendation that was floated and not
|
|
66
|
+
* adopted. `should` and `could` are deliberately absent from the durable
|
|
67
|
+
* marker table below - they are how advice is phrased, not how a ruling is
|
|
68
|
+
* stated - so a hedged sentence has to be refused explicitly.
|
|
69
|
+
*/
|
|
70
|
+
const HEDGE = /\b(?:maybe|perhaps|might|could|would|possibly|probably|consider|i think|i guess|not sure|unsure|what if|why not|we should probably)\b/i;
|
|
71
|
+
/**
|
|
72
|
+
* Absolute frames that make a hedged sentence a ruling anyway: "maybe we should
|
|
73
|
+
* never post through an API" has still ruled, while "we could consider APIs"
|
|
74
|
+
* has not.
|
|
75
|
+
*/
|
|
76
|
+
const ABSOLUTE = /\b(?:never|must|always|only one|required|mandatory|forbidden|banned|not allowed|by default|from now on|going forward)\b/i;
|
|
77
|
+
/**
|
|
78
|
+
* Opening words that make a sentence a question, used only together with a
|
|
79
|
+
* question mark: the mark alone is enough at the end of a body, but a body that
|
|
80
|
+
* opens with a question and closes with a ruling keeps its ruling.
|
|
81
|
+
*/
|
|
82
|
+
const INTERROGATIVE_OPENER = /^\s*(?:how|what|why|when|where|which|who|whose|whether)\b/i;
|
|
83
|
+
const QUESTION_OPENER = /^(?:should|shall|can|could|may|might|do|does|did|is|are|was|were|will|would|have|has|how|what|why|when|where|which|who|whose|am|if)\b/i;
|
|
84
|
+
/**
|
|
85
|
+
* Decision frames, in class-priority order. A frame is the grammar of a
|
|
86
|
+
* standing instruction rather than of this turn's work: an absolute (`never`,
|
|
87
|
+
* `always`, `must`, `only one`), a comparison between ways of doing something
|
|
88
|
+
* (`prefer`, `instead of`, `rather than`, `better than`), or a prescription
|
|
89
|
+
* stated in the collective voice (`we need to`, `should`). Bare imperatives are
|
|
90
|
+
* deliberately absent: "investigate X" is a task for this turn, and a table
|
|
91
|
+
* built from every imperative is a task list filed as policy.
|
|
92
|
+
*/
|
|
93
|
+
const MARKERS = [
|
|
94
|
+
{
|
|
95
|
+
class: "prohibition",
|
|
96
|
+
pattern: /\b(?:never|don't|do not|must not|may not|not allowed|forbidden|banned|no longer|stop (?:using|doing|running|adding|writing|posting|editing|treating))\b/i,
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
class: "preference",
|
|
100
|
+
pattern: /\b(?:prefer|preferably|instead of|rather than|better than|avoid)\b/i,
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
class: "requirement",
|
|
104
|
+
pattern: /\b(?:must|should|always|required|mandatory|only one|need(?:s)? to|have to|has to)\b/i,
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
class: "policy",
|
|
108
|
+
pattern: /\b(?:by default|default is|from now on|going forward|rule is|policy|standard|convention|principle)\b/i,
|
|
109
|
+
},
|
|
110
|
+
];
|
|
111
|
+
/** Abbreviations whose period does not end a sentence. */
|
|
112
|
+
const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|cf|approx|resp|no|dr|mr|mrs|ms|st)\.$/i;
|
|
113
|
+
/**
|
|
114
|
+
* Split a body into contiguous sentence spans.
|
|
115
|
+
*
|
|
116
|
+
* The spans are offsets into the original string, so a quote assembled from
|
|
117
|
+
* them is a byte-for-byte slice of the words - the property the pointer check
|
|
118
|
+
* leans on. Newlines end a sentence; a period does not end one inside a known
|
|
119
|
+
* abbreviation, a number (`3.5`), or a path (`decision-grammar.ts`).
|
|
120
|
+
*/
|
|
121
|
+
function sentenceSpans(text) {
|
|
122
|
+
const spans = [];
|
|
123
|
+
let start = 0;
|
|
124
|
+
const push = (end) => {
|
|
125
|
+
if (end > start) {
|
|
126
|
+
const slice = text.slice(start, end);
|
|
127
|
+
if (slice.trim())
|
|
128
|
+
spans.push({ start, end });
|
|
129
|
+
}
|
|
130
|
+
start = end;
|
|
131
|
+
};
|
|
132
|
+
for (let i = 0; i < text.length; i++) {
|
|
133
|
+
const ch = text[i];
|
|
134
|
+
if (ch === "\n") {
|
|
135
|
+
push(i);
|
|
136
|
+
continue;
|
|
137
|
+
}
|
|
138
|
+
if (ch !== "." && ch !== "!" && ch !== "?")
|
|
139
|
+
continue;
|
|
140
|
+
const next = text[i + 1];
|
|
141
|
+
if (next !== undefined && !/\s/.test(next))
|
|
142
|
+
continue;
|
|
143
|
+
if (ch === "." && ABBREVIATION.test(text.slice(Math.max(0, i - 12), i + 1)))
|
|
144
|
+
continue;
|
|
145
|
+
if (ch === "." && /\d$/.test(text[i - 1] ?? "") && /^\d/.test(next ?? ""))
|
|
146
|
+
continue;
|
|
147
|
+
push(i + 1);
|
|
148
|
+
}
|
|
149
|
+
push(text.length);
|
|
150
|
+
return spans;
|
|
151
|
+
}
|
|
152
|
+
/** Words in a string, counted the way a reader would. */
|
|
153
|
+
function wordCount(text) {
|
|
154
|
+
return text.split(/\s+/).filter(Boolean).length;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Is the body a paste - a shell transcript, a code block, a log or a payload?
|
|
158
|
+
*
|
|
159
|
+
* A pasted command is the single most common false ruling: it carries
|
|
160
|
+
* imperatives ("rm -rf"), digits, and often the word "only". The screens are
|
|
161
|
+
* cheap because a ruling sentence is prose, and prose does not start every line
|
|
162
|
+
* with a prompt, a box, or a stack frame.
|
|
163
|
+
*/
|
|
164
|
+
function looksPasted(text) {
|
|
165
|
+
if (text.includes("```"))
|
|
166
|
+
return true;
|
|
167
|
+
if (/^\s*[{[]/.test(text))
|
|
168
|
+
return true;
|
|
169
|
+
if (/^\s*(?:\$|%|> |#!)\s/m.test(text))
|
|
170
|
+
return true;
|
|
171
|
+
if (/(?:^|\n)\s*(?:[│├└─]|\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2})/m.test(text))
|
|
172
|
+
return true;
|
|
173
|
+
if (/Traceback \(most recent call last\)|\bat [\w$.]+ \([\w/.-]+:\d+:\d+\)/.test(text))
|
|
174
|
+
return true;
|
|
175
|
+
const lines = text.split("\n").filter((line) => line.trim());
|
|
176
|
+
const commandLines = lines.filter((line) => /^\s*(?:sudo |git |npm |npx |node |python3? |cd |ls |cat |rg |grep |curl |chmod |brew |make |docker |kubectl |export |rm )/.test(line));
|
|
177
|
+
if (commandLines.length >= 2)
|
|
178
|
+
return true;
|
|
179
|
+
// A payload of paths and key=value rows, with almost no sentence structure.
|
|
180
|
+
if (lines.length >= 6 && lines.every((line) => line.length < 200)) {
|
|
181
|
+
const payloadish = lines.filter((line) => /^[\w./-]{2,}\s*[:=]\s*\S/.test(line));
|
|
182
|
+
if (payloadish.length >= lines.length / 2)
|
|
183
|
+
return true;
|
|
184
|
+
}
|
|
185
|
+
return false;
|
|
186
|
+
}
|
|
187
|
+
/** Does the body end in a question, or open with one and carry nothing after it? */
|
|
188
|
+
function isQuestionShaped(text, spans) {
|
|
189
|
+
const trimmed = text.trimEnd();
|
|
190
|
+
if (trimmed.endsWith("?"))
|
|
191
|
+
return true;
|
|
192
|
+
const first = spans[0] ? text.slice(spans[0].start, spans[0].end).trim() : "";
|
|
193
|
+
return QUESTION_OPENER.test(first) && first.includes("?") && spans.length === 1;
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* The class a sentence marks, or `null` when it marks no standing instruction.
|
|
197
|
+
* First match in table order wins, so "must never" reads as a prohibition and
|
|
198
|
+
* "always prefer" as a preference.
|
|
199
|
+
*/
|
|
200
|
+
function markerClass(sentence) {
|
|
201
|
+
for (const { class: kind, pattern } of MARKERS) {
|
|
202
|
+
if (pattern.test(sentence))
|
|
203
|
+
return kind;
|
|
204
|
+
}
|
|
205
|
+
return null;
|
|
206
|
+
}
|
|
207
|
+
/**
|
|
208
|
+
* Assemble the quote: the sentence that carries the marker, plus its immediate
|
|
209
|
+
* continuation while that stays short. Contiguous, never reordered, never
|
|
210
|
+
* stitched from two places in the body.
|
|
211
|
+
*/
|
|
212
|
+
function quoteFrom(text, spans, markerIndex) {
|
|
213
|
+
let end = spans[markerIndex].end;
|
|
214
|
+
const next = spans[markerIndex + 1];
|
|
215
|
+
if (next) {
|
|
216
|
+
const candidate = text.slice(spans[markerIndex].start, next.end);
|
|
217
|
+
if (candidate.length <= CONTINUATION_LIMIT)
|
|
218
|
+
end = next.end;
|
|
219
|
+
}
|
|
220
|
+
const quote = text.slice(spans[markerIndex].start, end).trim();
|
|
221
|
+
if (quote.length <= QUOTE_LIMIT)
|
|
222
|
+
return quote;
|
|
223
|
+
return `${quote.slice(0, QUOTE_LIMIT).trimEnd()}...`;
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* Classify one body that is already known to be owner speech.
|
|
227
|
+
*
|
|
228
|
+
* Returns `null` for everything that is not a standing instruction: a question,
|
|
229
|
+
* a paste, a status report, a hedged recommendation, an acknowledgement, a
|
|
230
|
+
* second-person directive, or a body too long to cut a self-contained sentence
|
|
231
|
+
* from. Returns the class and the verbatim quote otherwise. The caller owns the
|
|
232
|
+
* provenance fields, because the caller is the one that knows where the text
|
|
233
|
+
* came from.
|
|
234
|
+
*/
|
|
235
|
+
export function classifyRulingBody(text, vocabulary) {
|
|
236
|
+
if (typeof text !== "string")
|
|
237
|
+
return null;
|
|
238
|
+
const body = text.trim();
|
|
239
|
+
if (!body)
|
|
240
|
+
return null;
|
|
241
|
+
if (wordCount(body) < MIN_TURN_WORDS)
|
|
242
|
+
return null;
|
|
243
|
+
if (body.length > MAX_TURN_CHARS)
|
|
244
|
+
return null;
|
|
245
|
+
if (looksPasted(body))
|
|
246
|
+
return null;
|
|
247
|
+
const spans = sentenceSpans(body);
|
|
248
|
+
if (spans.length === 0)
|
|
249
|
+
return null;
|
|
250
|
+
if (isQuestionShaped(body, spans))
|
|
251
|
+
return null;
|
|
252
|
+
const firstSentence = body.slice(spans[0].start, spans[0].end).trim();
|
|
253
|
+
if (STATUS_OPENER.test(firstSentence))
|
|
254
|
+
return null;
|
|
255
|
+
if (INTERROGATIVE_OPENER.test(firstSentence))
|
|
256
|
+
return null;
|
|
257
|
+
const firstPerson = FIRST_PERSON.test(body);
|
|
258
|
+
if (SECOND_PERSON.test(body) && !vocabulary.generalizes(body))
|
|
259
|
+
return null;
|
|
260
|
+
if (!firstPerson && !vocabulary.namesSubject(body))
|
|
261
|
+
return null;
|
|
262
|
+
if (!firstPerson && vocabulary.talksProcess(body))
|
|
263
|
+
return null;
|
|
264
|
+
for (let index = 0; index < spans.length; index++) {
|
|
265
|
+
const sentence = body.slice(spans[index].start, spans[index].end).trim();
|
|
266
|
+
const kind = markerClass(sentence);
|
|
267
|
+
if (!kind)
|
|
268
|
+
continue;
|
|
269
|
+
if (STATUS_OPENER.test(sentence))
|
|
270
|
+
continue;
|
|
271
|
+
if (CONVERSATIONAL.test(sentence))
|
|
272
|
+
continue;
|
|
273
|
+
if (sentence.includes("?"))
|
|
274
|
+
continue;
|
|
275
|
+
if (SECOND_PERSON.test(sentence) && !vocabulary.generalizes(sentence))
|
|
276
|
+
continue;
|
|
277
|
+
// The same voice test the body passed, applied to the sentence that will
|
|
278
|
+
// be quoted: a bare directive lifted out of a longer message is an
|
|
279
|
+
// instruction for the reader, not a decision about the system.
|
|
280
|
+
const sentenceFirstPerson = FIRST_PERSON.test(sentence);
|
|
281
|
+
if (!sentenceFirstPerson && !vocabulary.namesSubject(sentence))
|
|
282
|
+
continue;
|
|
283
|
+
if (!sentenceFirstPerson && vocabulary.talksProcess(sentence))
|
|
284
|
+
continue;
|
|
285
|
+
if (REPORT_VOICE.test(sentence) &&
|
|
286
|
+
!/^\s*(?:never|always|prefer|must not|by default|from now on)/i.test(sentence)) {
|
|
287
|
+
continue;
|
|
288
|
+
}
|
|
289
|
+
if (HEDGE.test(sentence) && !ABSOLUTE.test(sentence))
|
|
290
|
+
continue;
|
|
291
|
+
const quote = quoteFrom(body, spans, index);
|
|
292
|
+
if (!quote)
|
|
293
|
+
continue;
|
|
294
|
+
return { class: kind, quote };
|
|
295
|
+
}
|
|
296
|
+
return null;
|
|
297
|
+
}
|
|
298
|
+
// ── Tag derivation ──────────────────────────────────────────────────────────
|
|
299
|
+
/** How many tags a ruling carries. */
|
|
300
|
+
export const TAG_LIMIT = 3;
|
|
301
|
+
/** Shortest token a tag may be cut from. */
|
|
302
|
+
const TAG_TOKEN_MIN_LENGTH = 4;
|
|
303
|
+
/**
|
|
304
|
+
* The share of the population past which a token names nothing. A word a
|
|
305
|
+
* quarter of the store already carries is the store's background, not a topic:
|
|
306
|
+
* it would fire on every query and add nothing a reader could act on.
|
|
307
|
+
*/
|
|
308
|
+
const TAG_POPULATION_SHARE = 0.25;
|
|
309
|
+
/** Tokens a tag may be cut from: letters, then letters/digits/hyphens. */
|
|
310
|
+
const TAG_TOKEN = /[a-z][a-z0-9-]{3,}/g;
|
|
311
|
+
/**
|
|
312
|
+
* The tags a quote earns from the population it is filed into.
|
|
313
|
+
*
|
|
314
|
+
* Take the quote's tokens of four characters or more, drop the read path's stop
|
|
315
|
+
* words, drop any token more than a quarter of the population carries, and keep
|
|
316
|
+
* the three the population carries most, ties by first occurrence.
|
|
317
|
+
*
|
|
318
|
+
* The ranking is by frequency and not by rarity, and the reason is the read
|
|
319
|
+
* path's own arithmetic: a tag's bonus is a flat constant however rare the
|
|
320
|
+
* token is, so rarity buys nothing a later query will say. Two tokens of equal
|
|
321
|
+
* rarity are worth the same as tags, and the one a question is likelier to name
|
|
322
|
+
* is the one the population's own prose uses more often. That makes the
|
|
323
|
+
* frequency ranking the findability ranking, and it leaves the 25% cap as the
|
|
324
|
+
* only guard against a tag that names nothing.
|
|
325
|
+
*/
|
|
326
|
+
export function deriveTopicTags(text, population, limit = TAG_LIMIT) {
|
|
327
|
+
const ceiling = population.total * TAG_POPULATION_SHARE;
|
|
328
|
+
const seen = new Set();
|
|
329
|
+
const candidates = [];
|
|
330
|
+
for (const token of String(text ?? "")
|
|
331
|
+
.toLowerCase()
|
|
332
|
+
.match(TAG_TOKEN) ?? []) {
|
|
333
|
+
if (token.length < TAG_TOKEN_MIN_LENGTH)
|
|
334
|
+
continue;
|
|
335
|
+
if (QUERY_STOP_WORDS.has(token))
|
|
336
|
+
continue;
|
|
337
|
+
if (seen.has(token))
|
|
338
|
+
continue;
|
|
339
|
+
seen.add(token);
|
|
340
|
+
const count = population.count(token);
|
|
341
|
+
if (count > ceiling)
|
|
342
|
+
continue;
|
|
343
|
+
candidates.push({ token, count, first: candidates.length });
|
|
344
|
+
}
|
|
345
|
+
candidates.sort((a, b) => b.count - a.count || a.first - b.first);
|
|
346
|
+
return candidates.slice(0, limit).map((candidate) => candidate.token);
|
|
347
|
+
}
|
|
348
|
+
//# sourceMappingURL=decision-grammar.js.map
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
import type { CognitiveMemoryType, CognitiveMemoryEntry, CognitiveMemoryStore, MemoryContext, MemoryLink } from "./types.js";
|
|
8
8
|
export type { CognitiveMemoryType, MemorySource, MemoryContext, MemoryLink, CognitiveMemoryEntry, CognitiveMemoryStore, } from "./types.js";
|
|
9
9
|
export { formatMemoryTimestamp, formatMemoryEntry, parseStructuredContent, generateAutoTags, } from "./utils.js";
|
|
10
|
+
export { classifyRulingBody, deriveTopicTags, QUOTE_LIMIT, TAG_LIMIT, type GrammarVocabulary, type RulingClass, type RulingShape, type TagPopulation, } from "./decision-grammar.js";
|
|
10
11
|
export declare function getCognitiveMemory(): CognitiveMemory;
|
|
11
12
|
export declare class CognitiveMemory {
|
|
12
13
|
private memoryStore;
|
package/dist/lib/memory/index.js
CHANGED
|
@@ -13,6 +13,7 @@ import { generateAutoTags, generateId } from "./utils.js";
|
|
|
13
13
|
// CONSOLIDATION_INTERVAL stays here.
|
|
14
14
|
const _log = createLogger("semantic-memory");
|
|
15
15
|
export { formatMemoryTimestamp, formatMemoryEntry, parseStructuredContent, generateAutoTags, } from "./utils.js";
|
|
16
|
+
export { classifyRulingBody, deriveTopicTags, QUOTE_LIMIT, TAG_LIMIT, } from "./decision-grammar.js";
|
|
16
17
|
// shouldStore, calculateUtility, pruneMemories, consolidate, and the
|
|
17
18
|
// constants (MAX_ENTRIES, MIN_UTILITY_THRESHOLD, CATEGORY_BASE_UTILITY)
|
|
18
19
|
// are now in ./lifecycle.ts. The class below uses them.
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Owner speech: the braid half of the ruling write path.
|
|
3
|
+
*
|
|
4
|
+
* Two jobs, both of them specific to this deployment:
|
|
5
|
+
*
|
|
6
|
+
* - **Decide whether a turn is the owner speaking at all.** The corpus holds
|
|
7
|
+
* every user-role turn, and in this transcript tree that includes the
|
|
8
|
+
* system's own voice: dispatch prompts the seat writes to a running agent,
|
|
9
|
+
* and whisper envelopes from braid's subsystems. A directive-language
|
|
10
|
+
* classifier over that input files the seat's own brief text as an owner
|
|
11
|
+
* ruling, with a pointer into a worker session - a store that looks like
|
|
12
|
+
* provenance and is self-quotation. A telegram envelope is the exception:
|
|
13
|
+
* its body is the owner's message in a transport wrapper, so the wrapper is
|
|
14
|
+
* stripped and the body is what gets classified.
|
|
15
|
+
* - **File a ruling in braid's store.** The label stamped into `source`, the
|
|
16
|
+
* pointer shape, the duplicate key and the fixed tags are braid's filing
|
|
17
|
+
* convention, not English grammar, so they live here and the script that
|
|
18
|
+
* writes them carries no domain string of its own.
|
|
19
|
+
*
|
|
20
|
+
* The classification itself is `classifyRulingBody()` in the generic layer.
|
|
21
|
+
* This module supplies the vocabulary that layer cannot know - what a ruling
|
|
22
|
+
* can be about, and which words describe braid's own machinery - and removes
|
|
23
|
+
* the envelope before it ever reaches the grammar.
|
|
24
|
+
*
|
|
25
|
+
* Pure by construction: no I/O, no clock, no randomness.
|
|
26
|
+
*/
|
|
27
|
+
import { type GrammarVocabulary, type RulingClass } from "../memory/decision-grammar.js";
|
|
28
|
+
/**
|
|
29
|
+
* One user turn, in the shape the corpus index stores it. Declared here rather
|
|
30
|
+
* than imported from `extensions/memory/session-recall/corpus-index.ts`: `lib/`
|
|
31
|
+
* does not import from `extensions/`, and the classifier needs six fields, not
|
|
32
|
+
* that module's build machinery.
|
|
33
|
+
*/
|
|
34
|
+
export interface RulingTurn {
|
|
35
|
+
/** Absolute path of the session file the turn was read from. */
|
|
36
|
+
session: string;
|
|
37
|
+
/** pi's session id; with `line` it is the duplicate key. */
|
|
38
|
+
session_id: string;
|
|
39
|
+
/** Project label the session ran in. */
|
|
40
|
+
project: string;
|
|
41
|
+
/** Entry timestamp, ISO-8601. */
|
|
42
|
+
ts: string;
|
|
43
|
+
/** 1-based line number of the turn inside the session file. */
|
|
44
|
+
line: number;
|
|
45
|
+
/** The owner's words, verbatim. */
|
|
46
|
+
text: string;
|
|
47
|
+
}
|
|
48
|
+
/** A turn the classifier judged to carry an owner ruling. */
|
|
49
|
+
export interface OwnerRulingCandidate {
|
|
50
|
+
class: RulingClass;
|
|
51
|
+
/** The owner's words, contiguous and verbatim, capped with a trailing ellipsis. */
|
|
52
|
+
quote: string;
|
|
53
|
+
session: string;
|
|
54
|
+
session_id: string;
|
|
55
|
+
project: string;
|
|
56
|
+
ts: string;
|
|
57
|
+
line: number;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The label every filed ruling carries at the front of `source`, and the only
|
|
61
|
+
* handle a later run greps for. It is a constant here because the store's
|
|
62
|
+
* retention policy keys on the same prefix: a second spelling would be a class
|
|
63
|
+
* of entry the prune could not see.
|
|
64
|
+
*/
|
|
65
|
+
export declare const OWNER_RULING_LABEL = "owner ruling";
|
|
66
|
+
/**
|
|
67
|
+
* The vocabulary this deployment hands the generic grammar. It is the only
|
|
68
|
+
* braid-specific input `classifyRulingBody()` takes, and it is a value rather
|
|
69
|
+
* than a parameter chain so a fixture can classify the same body with and
|
|
70
|
+
* without an envelope and compare.
|
|
71
|
+
*/
|
|
72
|
+
export declare const BRAID_VOCABULARY: GrammarVocabulary;
|
|
73
|
+
/**
|
|
74
|
+
* Classify one user turn.
|
|
75
|
+
*
|
|
76
|
+
* Refuses everything that is not owner speech before the grammar runs, then
|
|
77
|
+
* hands the body to the generic classifier with this deployment's vocabulary,
|
|
78
|
+
* and stamps the provenance the pointer and the duplicate key are built from.
|
|
79
|
+
*/
|
|
80
|
+
export declare function classifyOwnerRuling(turn: RulingTurn): OwnerRulingCandidate | null;
|
|
81
|
+
/**
|
|
82
|
+
* The pointer the store carries in `source`, in one fixed shape:
|
|
83
|
+
* `owner ruling: <session path>:<line> (<iso ts>, <project>)`.
|
|
84
|
+
*
|
|
85
|
+
* Greppable by prefix, and it resolves: the path and line address the turn the
|
|
86
|
+
* quote came from, so `sed -n '<line>p' '<session path>'` prints the words.
|
|
87
|
+
*/
|
|
88
|
+
export declare function rulingPointer(candidate: OwnerRulingCandidate): string;
|
|
89
|
+
/**
|
|
90
|
+
* The pointer as a pattern, so a caller that scans a store for filed rulings
|
|
91
|
+
* reads the label from the same place it writes it instead of spelling it a
|
|
92
|
+
* second time. Groups: 1 the session path, 2 the line number.
|
|
93
|
+
*/
|
|
94
|
+
export declare function rulingPointerPattern(): RegExp;
|
|
95
|
+
/**
|
|
96
|
+
* The duplicate key: one turn is one ruling, so `<session_id>:<line>` names it
|
|
97
|
+
* whether the entry was written by this script, by hand, or by a later run.
|
|
98
|
+
*/
|
|
99
|
+
export declare function rulingDuplicateKey(candidate: OwnerRulingCandidate): string;
|
|
100
|
+
/**
|
|
101
|
+
* A project label as a tag token: lowercase alphanumerics, single hyphens, no
|
|
102
|
+
* leading/trailing hyphen. `projects/agents/pi-braid` becomes
|
|
103
|
+
* `projects-agents-pi-braid`, which is greppable and cannot collide with a
|
|
104
|
+
* different project's label through punctuation alone.
|
|
105
|
+
*/
|
|
106
|
+
export declare function projectTag(label: string): string;
|
|
107
|
+
/**
|
|
108
|
+
* The fixed handles every filed ruling carries: the class a reader filters on,
|
|
109
|
+
* and the project it came from. The quote's own words are added beside these by
|
|
110
|
+
* `deriveTopicTags()`, because a handle names the entry while a topic word is
|
|
111
|
+
* what a later question arrives through.
|
|
112
|
+
*/
|
|
113
|
+
export declare function rulingBaseTags(candidate: OwnerRulingCandidate): string[];
|
|
114
|
+
//# sourceMappingURL=owner-speech.d.ts.map
|