@dxos/brain 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/lib/Builtins.mjs +10 -2
  2. package/dist/lib/Builtins.mjs.map +1 -1
  3. package/dist/lib/Encoding.mjs +12 -2
  4. package/dist/lib/Encoding.mjs.map +1 -1
  5. package/dist/lib/Evaluator.mjs +144 -0
  6. package/dist/lib/Evaluator.mjs.map +1 -0
  7. package/dist/lib/GoalRules.mjs +153 -11
  8. package/dist/lib/GoalRules.mjs.map +1 -1
  9. package/dist/lib/Oracle.mjs +169 -0
  10. package/dist/lib/Oracle.mjs.map +1 -0
  11. package/dist/lib/index.mjs +3 -1
  12. package/dist/types/src/Builtins.d.ts +6 -0
  13. package/dist/types/src/Builtins.d.ts.map +1 -1
  14. package/dist/types/src/Encoding.d.ts +4 -0
  15. package/dist/types/src/Encoding.d.ts.map +1 -1
  16. package/dist/types/src/Encoding.test.d.ts +2 -0
  17. package/dist/types/src/Encoding.test.d.ts.map +1 -0
  18. package/dist/types/src/Evaluator.d.ts +77 -0
  19. package/dist/types/src/Evaluator.d.ts.map +1 -0
  20. package/dist/types/src/Evaluator.test.d.ts +2 -0
  21. package/dist/types/src/Evaluator.test.d.ts.map +1 -0
  22. package/dist/types/src/GoalRules.d.ts +66 -1
  23. package/dist/types/src/GoalRules.d.ts.map +1 -1
  24. package/dist/types/src/Oracle.d.ts +126 -0
  25. package/dist/types/src/Oracle.d.ts.map +1 -0
  26. package/dist/types/src/Oracle.test.d.ts +2 -0
  27. package/dist/types/src/Oracle.test.d.ts.map +1 -0
  28. package/dist/types/src/index.d.ts +2 -0
  29. package/dist/types/src/index.d.ts.map +1 -1
  30. package/dist/types/tsconfig.tsbuildinfo +1 -1
  31. package/package.json +15 -5
  32. package/src/Builtins.ts +12 -1
  33. package/src/Encoding.test.ts +93 -0
  34. package/src/Encoding.ts +9 -0
  35. package/src/Evaluator.test.ts +158 -0
  36. package/src/Evaluator.ts +186 -0
  37. package/src/GoalRules.test.ts +98 -0
  38. package/src/GoalRules.ts +212 -10
  39. package/src/Oracle.test.ts +71 -0
  40. package/src/Oracle.ts +182 -0
  41. package/src/index.ts +2 -0
package/src/GoalRules.ts CHANGED
@@ -6,6 +6,7 @@
6
6
 
7
7
  import type * as Ast from '@dxos/datalog/Ast';
8
8
  import * as Engine from '@dxos/datalog/Engine';
9
+ import { BaseError } from '@dxos/errors';
9
10
  import { RDF } from '@dxos/pipeline-rdf';
10
11
 
11
12
  import * as Builtins from './Builtins.ts';
@@ -13,6 +14,22 @@ import * as Compiler from './Compiler.ts';
13
14
  import * as Encoding from './Encoding.ts';
14
15
  import type * as Vocabulary from './Vocabulary.ts';
15
16
 
17
+ /**
18
+ * Size of the evaluator's working memory: past it the oldest facts retire, so a goal that runs
19
+ * indefinitely keeps a bounded engine, text and entity index (and bounded queries over them).
20
+ */
21
+ export const MAX_FACTS = 10_000;
22
+
23
+ /** Most sub-goals one evaluator tracks; sub-goals are structural, so exceeding it is an error. */
24
+ export const MAX_SUBGOALS = 256;
25
+
26
+ /** Thrown by `GoalRules.update` when an input would take the evaluator past {@link MAX_SUBGOALS}. */
27
+ export class CapacityError extends BaseError.extend('CapacityError', 'Goal evaluator capacity exceeded') {
28
+ constructor(context: { readonly max: number; readonly requested: number }) {
29
+ super({ message: `Goal evaluator would hold ${context.requested} sub-goals; the cap is ${context.max}.`, context });
30
+ }
31
+ }
32
+
16
33
  /** A reason to run judgment on the goal. */
17
34
  export type Wake = {
18
35
  /** The wake rule's label, `achieved`, or the sub-goal whose status changed. */
@@ -51,6 +68,18 @@ export type Options = {
51
68
  readonly entities?: Builtins.EntityIndex;
52
69
  /** Entities a fact concerns; defaults to its subject. */
53
70
  readonly concerns?: (fact: RDF.Fact) => ReadonlyArray<string>;
71
+ /**
72
+ * Working-memory size; defaults to {@link MAX_FACTS}. Each `update` first retires facts whose
73
+ * `assertion.validTo` is before the clock, then the oldest (by `generatedAtTime`, then arrival)
74
+ * until at most `maxFacts` remain. Retiring drops a fact from the evaluator only; the feed and any
75
+ * external index keep it, and a re-sent fact with a retired id is admitted again as new.
76
+ * Retirement never wakes the goal, and the facts behind the current `achieved` derivation are
77
+ * never retired, so a goal stays achieved once it is; `holds` and wake bindings may lapse as
78
+ * their facts retire, and a lapsed binding wakes again when new facts restore it.
79
+ */
80
+ readonly maxFacts?: number;
81
+ /** Overrides {@link MAX_SUBGOALS}. */
82
+ readonly maxSubgoals?: number;
54
83
  };
55
84
 
56
85
  export type Input = {
@@ -73,16 +102,24 @@ export class GoalRules {
73
102
  readonly #text: Builtins.TextIndex;
74
103
  readonly #entities: Builtins.EntityIndex;
75
104
  readonly #concerns: (fact: RDF.Fact) => ReadonlyArray<string>;
76
- readonly #saidAt = new Map<string, number>();
105
+ /** Working memory in arrival order. */
106
+ readonly #facts = new Map<string, Admitted>();
77
107
  readonly #subgoals = new Map<string, string>();
108
+ readonly #maxFacts: number;
109
+ readonly #maxSubgoals: number;
110
+ readonly #createdAt: number;
78
111
  #now: number;
79
112
  #previous: number;
80
113
  #achieved = false;
114
+ #sequence = 0;
81
115
 
82
116
  /** @throws Compiler.CompileError if the rules do not compile. */
83
117
  constructor(options: Options) {
118
+ this.#createdAt = options.createdAt;
84
119
  this.#now = options.createdAt;
85
120
  this.#previous = options.createdAt;
121
+ this.#maxFacts = options.maxFacts ?? MAX_FACTS;
122
+ this.#maxSubgoals = options.maxSubgoals ?? MAX_SUBGOALS;
86
123
  this.#vocabulary = options.vocabulary ?? Compiler.defaultVocabulary();
87
124
  this.#text = options.text ?? new Builtins.KeywordIndex();
88
125
  this.#entities = options.entities ?? new Builtins.MemoryEntityIndex();
@@ -92,7 +129,7 @@ export class GoalRules {
92
129
  now: () => this.#now,
93
130
  previous: () => this.#previous,
94
131
  createdAt: options.createdAt,
95
- saidAt: (factId) => this.#saidAt.get(factId),
132
+ saidAt: (factId) => this.#facts.get(factId)?.saidAt,
96
133
  },
97
134
  text: this.#text,
98
135
  entities: this.#entities,
@@ -110,17 +147,47 @@ export class GoalRules {
110
147
  return this.#engine.has('holds', ['goal']);
111
148
  }
112
149
 
113
- /** Adds facts and sub-goal status at time `at`; returns the wakes and the goal's state. */
150
+ /**
151
+ * Adds facts and sub-goal status at time `at`, retiring facts past the working-memory window
152
+ * (see {@link Options.maxFacts}); returns the wakes and the goal's state.
153
+ * @throws CapacityError if the input would exceed the sub-goal cap; nothing is applied.
154
+ */
114
155
  update({ at, facts = [], subgoals = {} }: Input): Evaluation {
156
+ this.#checkSubgoals(subgoals);
115
157
  this.#previous = this.#now;
116
158
  this.#now = at;
159
+
160
+ const arrived = new Map<string, { fact: RDF.Fact; admitted: Admitted }>();
161
+ for (const fact of facts) {
162
+ if (!this.#facts.has(fact.id) && !arrived.has(fact.id)) {
163
+ arrived.set(fact.id, { fact, admitted: this.#admit(fact) });
164
+ }
165
+ }
166
+ const retired = this.#retire([...arrived.values()].map(({ admitted }) => admitted));
167
+ const retiring: Engine.Entry[] = [];
168
+ for (const id of retired) {
169
+ const admitted = this.#facts.get(id);
170
+ if (admitted) {
171
+ retiring.push(...admitted.entries);
172
+ this.#facts.delete(id);
173
+ this.#text.remove(id);
174
+ this.#entities.remove(id);
175
+ }
176
+ }
177
+ if (retiring.length > 0) {
178
+ // A separate pass whose changes are discarded, so retirement never wakes the goal.
179
+ this.#engine.update({ retract: retiring });
180
+ }
181
+
117
182
  const insert: Engine.Entry[] = [];
118
183
  const retract: Engine.Entry[] = [];
119
- for (const fact of facts) {
120
- this.#saidAt.set(fact.id, Date.parse(fact.attribution.generatedAtTime));
121
- this.#text.add(fact.id, factText(fact));
122
- this.#entities.add(fact.id, this.#concerns(fact));
123
- insert.push(...Encoding.encode(fact, this.#vocabulary));
184
+ for (const { fact, admitted } of arrived.values()) {
185
+ if (!retired.has(fact.id)) {
186
+ this.#facts.set(fact.id, admitted);
187
+ this.#text.add(fact.id, factText(fact));
188
+ this.#entities.add(fact.id, this.#concerns(fact));
189
+ insert.push(...admitted.entries);
190
+ }
124
191
  }
125
192
 
126
193
  const wakes: Wake[] = [];
@@ -139,7 +206,16 @@ export class GoalRules {
139
206
  this.#subgoals.set(subgoal, status);
140
207
  }
141
208
 
142
- const changes = this.#engine.update({ insert, retract, refresh: this.#now !== this.#previous });
209
+ const refresh = this.#now !== this.#previous;
210
+ if (refresh) {
211
+ // Re-evaluate at the previous time with no period boundary crossed, discarding the changes: otherwise a
212
+ // binding `every` held at the previous evaluation is still present, and the next boundary adds nothing new.
213
+ const now = this.#now;
214
+ this.#now = this.#previous;
215
+ this.#engine.update({ refresh: true });
216
+ this.#now = now;
217
+ }
218
+ const changes = this.#engine.update({ insert, retract, refresh });
143
219
  for (const [relation, label] of this.compilation.wakes) {
144
220
  for (const tuple of changes.added.get(relation) ?? []) {
145
221
  wakes.push({ label, cause: 'rule', facts: Encoding.factIds(this.#engine.provenance(relation, tuple)) });
@@ -158,6 +234,115 @@ export class GoalRules {
158
234
  return { at, wakes, achieved, holds: this.holds };
159
235
  }
160
236
 
237
+ #checkSubgoals(subgoals: Readonly<Record<string, string>>): void {
238
+ const requested = this.#subgoals.size + Object.keys(subgoals).filter((id) => !this.#subgoals.has(id)).length;
239
+ if (requested > this.#maxSubgoals) {
240
+ throw new CapacityError({ max: this.#maxSubgoals, requested });
241
+ }
242
+ }
243
+
244
+ #admit(fact: RDF.Fact): Admitted {
245
+ const validTo = fact.assertion.validTo === undefined ? undefined : Date.parse(fact.assertion.validTo);
246
+ return {
247
+ id: fact.id,
248
+ sequence: this.#sequence++,
249
+ saidAt: Date.parse(fact.attribution.generatedAtTime),
250
+ validTo: validTo === undefined || Number.isNaN(validTo) ? undefined : validTo,
251
+ entries: Encoding.encode(fact, this.#vocabulary),
252
+ };
253
+ }
254
+
255
+ /** Ids to retire from working memory plus the arriving facts: expired first, then oldest past the cap. */
256
+ #retire(arriving: ReadonlyArray<Admitted>): Set<string> {
257
+ const pinned = new Set(this.achieved ? Encoding.factIds(this.#engine.provenance('achieved', ['goal'])) : []);
258
+ const retired = new Set<string>();
259
+ const kept: Admitted[] = [];
260
+ for (const admitted of [...this.#facts.values(), ...arriving]) {
261
+ if (!pinned.has(admitted.id) && admitted.validTo !== undefined && admitted.validTo < this.#now) {
262
+ retired.add(admitted.id);
263
+ } else {
264
+ kept.push(admitted);
265
+ }
266
+ }
267
+ let excess = kept.length - this.#maxFacts;
268
+ if (excess > 0) {
269
+ const oldest = kept
270
+ .filter(({ id }) => !pinned.has(id))
271
+ .sort((a, b) => age(a.saidAt) - age(b.saidAt) || a.sequence - b.sequence);
272
+ for (const { id } of oldest) {
273
+ if (excess-- <= 0) {
274
+ break;
275
+ }
276
+ retired.add(id);
277
+ }
278
+ }
279
+ return retired;
280
+ }
281
+
282
+ /**
283
+ * The earliest time after the last evaluation at which a time built-in can change its answer
284
+ * (`elapsed`, `every`, `due`), so a host schedules its next {@link update} rather than polling;
285
+ * `undefined` when the rules read no clock.
286
+ */
287
+ nextDueAt(): number | undefined {
288
+ const candidates: number[] = [];
289
+ const after = (time: number | undefined) => {
290
+ if (time !== undefined && time > this.#now) {
291
+ candidates.push(time);
292
+ }
293
+ };
294
+ const constant = (term: Ast.Term | undefined): Ast.Value | undefined =>
295
+ term?.type === 'constant' ? term.value : undefined;
296
+ const visit = (literal: Ast.Literal): void => {
297
+ if (literal.type === 'aggregate') {
298
+ literal.body.forEach(visit);
299
+ return;
300
+ }
301
+ if (literal.type !== 'atom') {
302
+ return;
303
+ }
304
+ const [first, second] = literal.atom.terms;
305
+ switch (literal.atom.predicate) {
306
+ case 'elapsed': {
307
+ const length = Builtins.parseDuration(constant(second) ?? '');
308
+ if (length === undefined) {
309
+ return;
310
+ }
311
+ const ref = constant(first);
312
+ if (ref === undefined) {
313
+ // `elapsed(F, …)` over facts: each fact in working memory starts its own clock.
314
+ for (const { saidAt } of this.#facts.values()) {
315
+ after(saidAt + length);
316
+ }
317
+ } else if (ref === 'goal') {
318
+ after(this.#createdAt + length);
319
+ } else {
320
+ const start = this.#facts.get(String(ref))?.saidAt ?? Builtins.parseTime(ref);
321
+ after(start === undefined ? undefined : start + length);
322
+ }
323
+ return;
324
+ }
325
+ case 'every': {
326
+ const period = Builtins.parseDuration(constant(first) ?? '');
327
+ if (period !== undefined && period > 0) {
328
+ after(this.#createdAt + (Math.floor((this.#now - this.#createdAt) / period) + 1) * period);
329
+ }
330
+ return;
331
+ }
332
+ case 'due': {
333
+ const deadline = Builtins.parseTime(constant(first) ?? '');
334
+ const lead = Builtins.parseDuration(constant(second) ?? '');
335
+ after(deadline === undefined || lead === undefined ? undefined : deadline - lead);
336
+ return;
337
+ }
338
+ }
339
+ };
340
+ for (const rule of this.compilation.program.rules) {
341
+ rule.body.forEach(visit);
342
+ }
343
+ return candidates.length === 0 ? undefined : Math.min(...candidates);
344
+ }
345
+
161
346
  /** Evaluates the `blocks` rules for a proposed action without keeping it. */
162
347
  checkAction(action: Action): ActionCheck {
163
348
  const entries: Engine.Entry[] = [
@@ -173,9 +358,26 @@ export class GoalRules {
173
358
  }
174
359
  }
175
360
 
361
+ /** A fact in working memory, with what retirement needs to order and retract it. */
362
+ type Admitted = {
363
+ readonly id: string;
364
+ /** Arrival order, the tie-break between facts said at the same time. */
365
+ readonly sequence: number;
366
+ readonly saidAt: number;
367
+ readonly validTo?: number;
368
+ readonly entries: ReadonlyArray<Engine.Entry>;
369
+ };
370
+
371
+ /** An unparseable `generatedAtTime` sorts as oldest. */
372
+ const age = (saidAt: number): number => (Number.isNaN(saidAt) ? Number.NEGATIVE_INFINITY : saidAt);
373
+
176
374
  /** Creates a goal evaluator. */
177
375
  export const make = (options: Options): GoalRules => new GoalRules(options);
178
376
 
377
+ /** A term's id and, for an entity known by an opaque id (a DID), its label, so `about` matches the name. */
378
+ const termText = (term: RDF.Term): string =>
379
+ term.kind === 'entity' && term.label !== undefined ? `${term.entity} ${term.label}` : RDF.termValue(term);
380
+
179
381
  /** The text `about` matches: what was said plus the triple. */
180
382
  const factText = ({ assertion }: RDF.Fact): string =>
181
- [assertion.quote ?? '', RDF.termValue(assertion.subject), assertion.predicate, RDF.termValue(assertion.object)].join(' ');
383
+ [assertion.quote ?? '', termText(assertion.subject), assertion.predicate, termText(assertion.object)].join(' ');
@@ -0,0 +1,71 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import * as Oracle from './Oracle.ts';
8
+ import { REFERENCE } from './testing/index.ts';
9
+
10
+ const CREATED = Date.parse('2027-01-04T09:00:00Z');
11
+
12
+ /** A timeline for goal 1 ("keep me informed about what Dima is working on"), as an oracle might write it. */
13
+ const TIMELINE = JSON.stringify({
14
+ steps: [
15
+ {
16
+ after: '10m',
17
+ says: [
18
+ {
19
+ speaker: 'rich',
20
+ quote: 'Lunch?',
21
+ subject: 'rich',
22
+ predicate: 'suggests',
23
+ object: 'lunch',
24
+ force: 'directive',
25
+ },
26
+ ],
27
+ wake: false,
28
+ note: 'unrelated, and not Dima',
29
+ },
30
+ {
31
+ after: '1h',
32
+ says: [
33
+ { speaker: 'dima', quote: 'I am on the indexer.', subject: 'dima', predicate: 'works on', object: 'indexer' },
34
+ ],
35
+ wake: true,
36
+ },
37
+ ],
38
+ });
39
+
40
+ describe('Oracle', () => {
41
+ test('parses a timeline, also inside a code fence', ({ expect }) => {
42
+ const reply = Oracle.parseReply(`Here it is:\n\`\`\`json\n${TIMELINE}\n\`\`\``);
43
+ expect(reply.steps.map(({ wake }) => wake)).toEqual([false, true]);
44
+ expect(() => Oracle.parseReply('no json')).toThrow(Oracle.ReplyError);
45
+ expect(() => Oracle.parseReply('{"steps":[]}')).toThrow(Oracle.ReplyError);
46
+ });
47
+
48
+ test('passes a compilation that replays the timeline and fails one that does not', ({ expect }) => {
49
+ const { steps } = Oracle.parseReply(TIMELINE);
50
+ expect(Oracle.replay(REFERENCE[1], { createdAt: CREATED, steps })).toEqual({ ok: true, failures: [] });
51
+
52
+ // Waking on anyone at all wakes on the near miss.
53
+ const loose = Oracle.replay('wake(any) :- fact(F, _, _, _).', { createdAt: CREATED, steps });
54
+ expect(loose.ok).toBe(false);
55
+ expect(loose.failures).toEqual([
56
+ expect.stringContaining('step 1 (unrelated, and not Dima): wake=true, expected false'),
57
+ ]);
58
+
59
+ // Rules that do not compile fail the gate rather than throw.
60
+ expect(Oracle.replay('wake(x) :- nonsense(', { createdAt: CREATED, steps }).ok).toBe(false);
61
+ });
62
+
63
+ test('tells the oracle the ids people go by', ({ expect }) => {
64
+ const message = Oracle.userMessage({
65
+ goal: 'Keep me posted on Bob',
66
+ owner: 'did:halo:ALICE',
67
+ people: [{ name: 'Bob', id: 'did:halo:BOB' }],
68
+ });
69
+ expect(message).toContain('Bob = did:halo:BOB');
70
+ });
71
+ });
package/src/Oracle.ts ADDED
@@ -0,0 +1,182 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ // @import-as-namespace
6
+
7
+ import * as Schema from 'effect/Schema';
8
+
9
+ import { BaseError } from '@dxos/errors';
10
+ import { type RDF } from '@dxos/pipeline-rdf';
11
+ import { trim } from '@dxos/util';
12
+
13
+ import * as Builtins from './Builtins.ts';
14
+ import * as Compiler from './Compiler.ts';
15
+ import * as GoalRules from './GoalRules.ts';
16
+
17
+ /**
18
+ * The replay gate's oracle (BRAIN.md, "Compilation"): a model call that sees only the goal's text and
19
+ * writes a short timeline of statements with what each should do to the goal. A compilation goes active
20
+ * only if it replays that timeline correctly; the oracle never sees the rules, so it cannot share the
21
+ * compiler's misreading of the goal.
22
+ */
23
+
24
+ /** One statement in a test timeline; people and things are named by the ids the goal was given. */
25
+ export const Statement = Schema.Struct({
26
+ speaker: Schema.String,
27
+ quote: Schema.String,
28
+ subject: Schema.String,
29
+ predicate: Schema.String,
30
+ object: Schema.String,
31
+ force: Schema.optional(Schema.Literals(['assertive', 'directive', 'commissive', 'expressive'])),
32
+ polarity: Schema.optional(Schema.Literals(['+', '-'])),
33
+ });
34
+ export interface Statement extends Schema.Schema.Type<typeof Statement> {}
35
+
36
+ /** A step of the timeline: when it happens after the goal is set, what is said, and what should follow. */
37
+ export const Step = Schema.Struct({
38
+ /** A duration after the goal was set, e.g. `10m`, `1h`, `3d`. */
39
+ after: Schema.String,
40
+ says: Schema.Array(Statement),
41
+ /** Whether the goal should wake (be judged) at this step. */
42
+ wake: Schema.Boolean,
43
+ /** Whether the goal should be achieved after this step; absent when either is acceptable. */
44
+ achieved: Schema.optional(Schema.Boolean),
45
+ note: Schema.optional(Schema.String),
46
+ });
47
+ export interface Step extends Schema.Schema.Type<typeof Step> {}
48
+
49
+ export const Reply = Schema.Struct({ steps: Schema.Array(Step) });
50
+ export interface Reply extends Schema.Schema.Type<typeof Reply> {}
51
+
52
+ export type Person = { readonly name: string; readonly id: string };
53
+
54
+ export type Goal = {
55
+ readonly goal: string;
56
+ readonly instructions?: string;
57
+ /** Id of the goal's owner. */
58
+ readonly owner: string;
59
+ /** People the goal may concern, with the ids statements must use for them. */
60
+ readonly people?: ReadonlyArray<Person>;
61
+ };
62
+
63
+ /** Thrown by {@link parseReply} when the reply is not a timeline. */
64
+ export class ReplyError extends BaseError.extend('OracleReplyError', 'Oracle reply is not a timeline') {}
65
+
66
+ /** The oracle's instructions. */
67
+ export const SYSTEM_PROMPT = trim`
68
+ You write acceptance tests for an agent's goal. A goal is a plain-text directive; a runtime will decide,
69
+ after every statement anyone makes, whether the goal should WAKE (the agent looks at it again because
70
+ something relevant happened) and whether it is ACHIEVED (its outcome happened). You do not see how the
71
+ runtime decides; you only describe what a careful person would expect.
72
+
73
+ Write a short timeline of 3 to 6 steps after the goal is set. Include at least one step that should
74
+ wake the goal and at least one near miss that should not (the wrong person, an unrelated topic, a
75
+ refusal or a question instead of a statement). Say only what is needed; each step usually has one
76
+ statement.
77
+
78
+ Each statement is one fact as an extractor would record it: who said it (speaker), the words as said
79
+ (quote), and a subject–predicate–object triple. Name people by the ids given with the goal, exactly as
80
+ given (e.g. "did:halo:…"); name other things with lowercase hyphenated words ("indexer-migration").
81
+ force is assertive (states), directive (asks), commissive (promises or agrees) or expressive; polarity
82
+ is "+" (affirmed) or "-" (denied, refused).
83
+
84
+ Reply with JSON only:
85
+ {"steps":[{"after":"10m","says":[{"speaker":"…","quote":"…","subject":"…","predicate":"…","object":"…","force":"assertive","polarity":"+"}],"wake":true,"achieved":false,"note":"why"}]}
86
+ "after" is a duration since the goal was set (10m, 2h, 3d) and must increase from step to step.
87
+ Leave "achieved" out when either answer would be acceptable.
88
+ `;
89
+
90
+ /** The user message for one goal. */
91
+ export const userMessage = ({ goal, instructions, owner, people = [] }: Goal): string =>
92
+ [
93
+ `Goal: "${goal}"`,
94
+ `Owner: ${owner}`,
95
+ instructions?.trim() ? `Instructions: ${instructions.trim()}` : undefined,
96
+ people.length > 0
97
+ ? `People (use these ids): ${people.map(({ name, id }) => `${name} = ${id}`).join('; ')}`
98
+ : undefined,
99
+ ]
100
+ .filter((line) => line !== undefined)
101
+ .join('\n');
102
+
103
+ const decode = Schema.decodeUnknownSync(Reply);
104
+
105
+ /**
106
+ * Extracts the timeline from the oracle's reply; tolerates a code fence or prose around the JSON.
107
+ * @throws ReplyError if there is no valid timeline.
108
+ */
109
+ export const parseReply = (text: string): Reply => {
110
+ const start = text.indexOf('{');
111
+ const end = text.lastIndexOf('}');
112
+ if (start < 0 || end <= start) {
113
+ throw new ReplyError({ message: 'the reply has no JSON object' });
114
+ }
115
+ try {
116
+ const reply = decode(JSON.parse(text.slice(start, end + 1)));
117
+ if (reply.steps.length === 0) {
118
+ throw new ReplyError({ message: 'the timeline is empty' });
119
+ }
120
+ return reply;
121
+ } catch (error) {
122
+ throw error instanceof ReplyError
123
+ ? error
124
+ : new ReplyError({ message: error instanceof Error ? error.message : String(error) });
125
+ }
126
+ };
127
+
128
+ /** A statement as the fact the extractor would record. */
129
+ const toFact = (statement: Statement, id: string, saidAt: string): RDF.Fact => ({
130
+ id,
131
+ assertion: {
132
+ subject: { kind: 'entity', entity: statement.subject },
133
+ predicate: statement.predicate,
134
+ object: { kind: 'entity', entity: statement.object },
135
+ quote: statement.quote,
136
+ },
137
+ factuality: { value: statement.polarity === '-' ? 'CT-' : 'CT+', polarity: statement.polarity ?? '+' },
138
+ illocution: { force: statement.force ?? 'assertive' },
139
+ attribution: { agent: statement.speaker, source: 'oracle', generatedAtTime: saidAt },
140
+ recordedAt: saidAt,
141
+ extractor: { id: 'oracle', model: 'none', version: '1' },
142
+ sourceHash: id,
143
+ });
144
+
145
+ export type Result = {
146
+ readonly ok: boolean;
147
+ /** One line per expectation the rules violate. */
148
+ readonly failures: ReadonlyArray<string>;
149
+ };
150
+
151
+ /** Replays the oracle's timeline against compiled rules; a compile error is a failure. */
152
+ export const replay = (
153
+ source: string,
154
+ { createdAt, steps }: { createdAt: number; steps: ReadonlyArray<Step> },
155
+ ): Result => {
156
+ let rules: GoalRules.GoalRules;
157
+ try {
158
+ rules = GoalRules.make({ source, createdAt });
159
+ } catch (error) {
160
+ if (error instanceof Compiler.CompileError) {
161
+ return { ok: false, failures: error.diagnostics.map(Compiler.formatDiagnostic) };
162
+ }
163
+ throw error;
164
+ }
165
+ const failures: string[] = [];
166
+ steps.forEach((step, index) => {
167
+ const offset = Builtins.parseDuration(step.after) ?? 0;
168
+ const saidAt = new Date(createdAt + offset).toISOString();
169
+ const { wakes, achieved } = rules.update({
170
+ at: createdAt + offset,
171
+ facts: step.says.map((statement, position) => toFact(statement, `oracle-${index}-${position}`, saidAt)),
172
+ });
173
+ const label = `step ${index + 1} (${step.note ?? step.says.map(({ quote }) => quote).join(' / ')})`;
174
+ if (wakes.length > 0 !== step.wake) {
175
+ failures.push(`${label}: wake=${wakes.length > 0}, expected ${step.wake}`);
176
+ }
177
+ if (step.achieved !== undefined && achieved !== step.achieved) {
178
+ failures.push(`${label}: achieved=${achieved}, expected ${step.achieved}`);
179
+ }
180
+ });
181
+ return { ok: failures.length === 0, failures };
182
+ };
package/src/index.ts CHANGED
@@ -6,5 +6,7 @@ export * as Builtins from './Builtins.ts';
6
6
  export * as CompilePrompt from './CompilePrompt.ts';
7
7
  export * as Compiler from './Compiler.ts';
8
8
  export * as Encoding from './Encoding.ts';
9
+ export * as Evaluator from './Evaluator.ts';
9
10
  export * as GoalRules from './GoalRules.ts';
11
+ export * as Oracle from './Oracle.ts';
10
12
  export * as Vocabulary from './Vocabulary.ts';