@dsh-agentic-roleplay/state 0.2.1 → 0.3.1

package/README.md

@@ -133,7 +133,7 @@ characters created during play have none.
 | `locations`, `exits`, `placements` | Places (with features), the ways between them (one direction each, `open` / `locked` / `blocked`, optional travel seconds) and where things stand (a character: place, position, feature; the same table will place items). `session.planMove` / `session.move` move a character over open exits only (`InvalidMoveError` names every reason); the edit wire format can make places, change exits and move characters. |
 | `events` | What objectively happened: turn, round, text, importance (1 to 5), tags. `event_involves` lists the characters an event is about. Events are immutable: a draft until `sealed`, final afterwards (`events.seal()`); updating or removing a sealed one throws `ConflictError`. |
 | `perceptions` | What one character took in of an event, in its own terms: mode (witnessed, heard, told, inferred), content, a gist for when it fades, an accuracy label (never shown to the character), and how often it was recalled. One per character and event. |
-| `memories` | What a character believes or knows beyond single events: kind (belief, relationship, knowledge), text, the characters it is about, importance, the turn it formed in. |
+| `memories`, `memory_evidence` | What a character believes or knows beyond single events: kind, text, subjects, importance, confidence, formation turn, and the perceptions that support or contradict it. |
 | `story_threads` | Things not settled yet: promises, mysteries, goals; open or resolved. |
 | `summaries` | The account of the story for the conversation's head: digests of recent turns and chapters of older ones, each with the turns it covers. |
 | `recall_items`, `recall_fts`, `recall_vocab`, `recall_vec` | The search index: one row per perception, memory and event, indexed by words (FTS5) and, once vectors are stored, by meaning (sqlite-vec, cosine, partitioned by character). `store.recallIndex` lists the texts without a vector (`pending`), stores vectors (`store`, which fixes the model and dimensions of the session's vectors) and searches (`lexical`, `vector`). Vector support is optional: without the extension everything but `vector` works. |

package/lib/index.d.ts

@@ -367,6 +367,11 @@ interface LocationDefinition {
 interface RoutineWindow {
   /** The days of the week it applies on, 0 for Sunday; every day when empty. A window past midnight belongs to the day it starts on. */
   days: number[];
+  /**
+   * Other days it applies on or does not (`dec`, `12-24`, `season:winter`, `nth:mon:1`, `holiday:<id>`, a `!` before one for a day it does not apply
+   * on): it applies on a day that is among `days` and that these allow. Every day when empty or left out.
+   */
+  on?: string[];
   /** The minute of the day it starts, 0 to 1439. */
   start: number;
   /** The minute it ends (exclusive); before `start` it ends the next day. Equal to `start` is not a window. */
@@ -380,6 +385,7 @@ interface RoutineWindow {
   interruptible: boolean;
 }
 interface StoredRoutineWindow extends RoutineWindow {
+  on: string[];
   id: number;
   characterId: CharacterId;
 }
@@ -387,6 +393,8 @@ interface StoredRoutineWindow extends RoutineWindow {
 interface RoutineDefinition {
   /** Three-letter days (`mon` to `sun`); every day when left out. */
   days: string[];
+  /** Other days it applies on or does not, as for {@link RoutineWindow.on}. */
+  on?: string[];
   /** `HH:MM`. */
   from: string;
   to: string;
@@ -714,6 +722,13 @@ declare const ACCURACIES: readonly ["accurate", "partial", "mistaken"];
 type Accuracy = (typeof ACCURACIES)[number];
 declare const MEMORY_KINDS: readonly ["belief", "relationship", "knowledge"];
 type MemoryKind = (typeof MEMORY_KINDS)[number];
+/** How sure a character is of what it believes, from least to most. */
+declare const MEMORY_CONFIDENCES: readonly ["doubtful", "likely", "sure"];
+type MemoryConfidence = (typeof MEMORY_CONFIDENCES)[number];
+declare const DEFAULT_CONFIDENCE: MemoryConfidence;
+/** Whether a perception speaks for a belief or against it. */
+declare const EVIDENCE_RELATIONS: readonly ["supports", "contradicts"];
+type EvidenceRelation = (typeof EVIDENCE_RELATIONS)[number];
 declare const THREAD_STATUSES: readonly ["open", "resolved"];
 type ThreadStatus = (typeof THREAD_STATUSES)[number];
 /** A digest covers a stretch of recent turns closely; a chapter covers older turns briefly. */
@@ -808,17 +823,30 @@ interface CharacterMemory {
   /** The characters it is about. */
   about: CharacterId[];
   importance: number;
+  /** How sure the character is of it. */
+  confidence: MemoryConfidence;
   /** The turn it was formed in. */
   turn: number;
   recalls: number;
   lastRecalledTurn?: number;
   createdAt: string;
 }
-type NewCharacterMemory = Omit<CharacterMemory, 'id' | 'createdAt' | 'recalls' | 'lastRecalledTurn'>;
+type NewCharacterMemory = Omit<CharacterMemory, 'id' | 'createdAt' | 'recalls' | 'lastRecalledTurn' | 'confidence'> & {
+  confidence?: MemoryConfidence;
+};
 interface CharacterMemoryPatch {
   text?: string;
   about?: CharacterId[];
   importance?: number;
+  confidence?: MemoryConfidence;
+}
+/** What a character took in that a belief rests on, or that speaks against it. */
+interface MemoryEvidence {
+  memoryId: MemoryId;
+  perceptionId: PerceptionId;
+  relation: EvidenceRelation;
+  /** The turn the link was made. */
+  turn: number;
 }
 /** Something in the story that is not settled yet: a promise, a mystery, a goal. */
 interface StoryThread {
@@ -1012,7 +1040,7 @@ type Comparison = (typeof COMPARISONS)[number];
  * the story's zone: `YYYY-MM-DDTHH:MM`, and `HH:MM` for a time of day.
  */
 type TriggerCondition =
-/** True from `from` on, until `to`; or while the time of day is in `window` (past midnight when it ends before it starts), on `days` (`mon` to `sun`) when given. */
+/** True from `from` on, until `to`; or while the time of day is in `window` (past midnight when it ends before it starts), on `days` (`mon` to `sun`) when given and on the days `on` allows (months, dates, seasons, holidays of the world's calendar). */
 {
   type: 'time';
   from?: string;
@@ -1022,6 +1050,7 @@ type TriggerCondition =
     to: string;
   };
   days?: string[];
+  on?: string[];
 } |
 /** A character is in a place, at a feature of it when given. */
 {
@@ -1088,6 +1117,8 @@ interface TriggerAnnouncement {
   /** When it is to happen, a local time, as told with the announcement; the time the condition waits for when it is a plain one, if left out. */
   at?: string;
 }
+/** In a cue, the key of the character it is said to: in a `while` condition and in the words of the cue. */
+declare const SELF = "@self";
 /** What happens when a trigger fires. */
 type TriggerEffect =
 /** A checked change of the story's records, in the format of an edit (events, variable changes, exit and item changes, moves, goals, engagements). */
@@ -1095,16 +1126,22 @@ type TriggerEffect =
   type: 'edit';
   edit: Record<string, unknown>;
 } |
-/** Something the game master is told to weave into the story, until it says it did or a few turns pass. */
+/**
+ * Something the game master is told to weave into the story, until it says it did or a few turns pass. It is written when it is told, not when
+ * the trigger fired: `text` may name things the story has by `{kind:key}` and so is said as the story stands then (see `TEMPLATE_KINDS`), and
+ * `while` is a condition that must still hold then, or the beat is withdrawn instead.
+ */
 {
   type: 'beat';
   text: string;
+  while?: TriggerCondition;
 } |
-/** Something the audience notices, said to each of them the next time they act. */
+/** Something the audience notices, said to each of them the next time they act; written, and withdrawn, as a beat is, for each of them (`SELF` is the one it is said to). */
 {
   type: 'cue';
   audience: TriggerAudience;
   text: string;
+  while?: TriggerCondition;
 };
 declare const TRIGGER_STATUSES: readonly ["dormant", "fired", "failed", "expired"];
 type TriggerStatus = (typeof TRIGGER_STATUSES)[number];
@@ -1248,6 +1285,24 @@ interface PlotProgress {
   lastNudgeAt?: number;
 }
 //#endregion
+//#region ../dsh-roleplay-model/src/messages.d.ts
+/** The languages the texts a model reads are written in. English is the source: a text is its own key. */
+declare const LANGUAGES: readonly ["en", "zh"];
+type Language = (typeof LANGUAGES)[number];
+/** The language a setting such as `zh-CN` or `en` stands for; English when it is none that is known. */
+declare function languageOf(code: string | undefined): Language;
+type MessageValues = Readonly<Record<string, string | number>>;
+/** Says a text in the language of the story: `tr('{name} is in {place}.', { name, place })`. */
+type Translate = (text: string, values?: MessageValues) => string;
+/**
+ * The texts the engine builds for a model (briefs, reports, refusals) in a language. The text written in the code is the English one and the key of
+ * the others; a text a language lacks is told in English, and a test keeps that from happening.
+ */
+declare function translator(language: Language): Translate;
+/** The texts with a translation, for the test that every text has one. */
+declare const translated: (language: Exclude<Language, "en">) => readonly string[];
+declare const translation: (language: Exclude<Language, "en">, text: string) => string | undefined;
+//#endregion
 //#region src/clock.d.ts
 type Clock = () => Date;
 declare const systemClock: Clock;
@@ -1474,6 +1529,17 @@ interface MemoryRepository {
   /** Count a memory as recalled in `turn`. */
   touch(ids: readonly MemoryId[], turn: number): void;
   remove(id: MemoryId): boolean;
+  /** Record that a perception of the character's speaks for a belief or against it; one link per pair, the later replaces the earlier. @throws {NotFoundError} */
+  addEvidence(memoryId: MemoryId, perceptionId: PerceptionId, relation: EvidenceRelation, turn: number): void;
+  evidenceOf(memoryId: MemoryId): MemoryEvidence[];
+  /**
+   * What a character's beliefs rest on: for each perception that some belief of the character cites, the beliefs that do (it is folded into them),
+   * and the beliefs something it took in speaks against (disputed).
+   */
+  evidenceIndex(characterId: CharacterId): {
+    folded: Map<PerceptionId, MemoryId[]>;
+    disputed: Set<MemoryId>;
+  };
 }
 interface ThreadRepository {
   open(text: string, turn: number): StoryThread;
@@ -1991,6 +2057,8 @@ interface RecordsTarget {
   routines: RoutineRepository;
   engagements: EngagementRepository;
   triggers: TriggerRepository;
+  /** What the story keeps about itself; the calendar of its world is read from here. */
+  metadata: Pick<MetadataRepository, 'getValue'>;
   transaction<T>(fn: () => T): T;
 }
 interface PerceivedBy {
@@ -2241,12 +2309,20 @@ interface NewBelief {
   text: string;
   about?: string[];
   importance: number;
+  /** How sure the character is; likely when not said. */
+  confidence?: MemoryConfidence;
+  /** The numbers of perceptions of the character's own that it rests on, and that speak against it. */
+  evidenceFor?: number[];
+  evidenceAgainst?: number[];
 }
 interface BeliefEdit {
   id: number;
   text?: string;
   about?: string[];
   importance?: number;
+  confidence?: MemoryConfidence;
+  evidenceFor?: number[];
+  evidenceAgainst?: number[];
 }
 /**
  * A change to the story's records, applied together or not at all: the unit in which the
@@ -2301,6 +2377,8 @@ interface EngagementEditSpec {
 interface RoutineWindowSpec {
   /** `mon` to `sun`; every day when left out. */
   days?: string[];
+  /** Other days it applies on or not: `dec`, `12-24`, `season:winter`, `nth:mon:1`, `holiday:<id>`, `!` before one for a day it does not apply on. */
+  on?: string[];
   /** `HH:MM`. */
   from: string;
   to: string;
@@ -2389,12 +2467,12 @@ declare function parseTriggerDefinition(value: unknown, path: string, checkEdit:
 } | {
   problems: string[];
 };
-type Reading = Pick<RecordsTarget, 'characters' | 'locations' | 'items' | 'variables' | 'triggers'>;
+type Reading$1 = Pick<RecordsTarget, 'characters' | 'locations' | 'items' | 'variables' | 'triggers' | 'metadata'>;
 /**
  * What in a trigger names something the story does not have: a character, place, item or variable in a condition, the characters of a cue,
  * a trigger it waits for. (What an edit effect touches is checked when it is applied.)
  */
-declare function triggerReferenceProblems(target: Reading, definition: TriggerDefinition, otherKeys?: Iterable<string>): string[];
+declare function triggerReferenceProblems(target: Reading$1, definition: TriggerDefinition, otherKeys?: Iterable<string>): string[];
 interface TriggerClock {
   now: number;
   zone: string;
@@ -2461,6 +2539,30 @@ declare function lapseNotes(target: RecordsTarget, turn: number, kept: {
   cues: number;
 }): TriggerNote[];
 //#endregion
+//#region src/records/deferred.d.ts
+type Reading = RecordsTarget;
+/** The words cannot be written as the story stands: something they name is not there. */
+declare class UnwritableError extends Error {}
+/** Words as the story stands now. @throws {UnwritableError} when something they name is not there. */
+declare function renderWords(target: Reading, text: string, clock: TriggerClock, self?: string): string;
+interface Delivery {
+  /** What is to be told now, in words as the story stands. */
+  shown: {
+    note: TriggerNote;
+    text: string;
+  }[];
+  /** What is not to be told, and why: the beat or cue no longer applies, or cannot be written. */
+  withdrawn: {
+    note: TriggerNote;
+    reason: string;
+  }[];
+}
+/**
+ * Decides, at the moment notes are about to be told, what is still to be told and in what words. A note whose effect says something must
+ * still hold and does not hold any more is withdrawn; so is one whose words name something that is not there. Nothing is changed.
+ */
+declare function deliverNotes(target: Reading, notes: readonly TriggerNote[], clock: TriggerClock): Delivery;
+//#endregion
 //#region src/records/movement.d.ts
 interface MoveContext {
   locations: Pick<LocationRepository, 'get' | 'allExits'>;
@@ -2512,6 +2614,11 @@ interface MemoryPolicy {
    * included) to 1 (only what adds something new): maximal marginal relevance over the pool. 0 or absent: none.
    */
   diversity?: number;
+  /**
+   * How long what a character took in lasts once a belief rests on it, as a share of how long it would last: below 1 it fades sooner, the
+   * belief having taken over, and it is not told again when that belief is told. 1 or absent: no change.
+   */
+  foldedFade?: number;
 }
 declare const DEFAULT_MEMORY_POLICY: MemoryPolicy;
 /** How much of a memory is left: what the character is told of it. */
@@ -2531,6 +2638,10 @@ interface Recalled {
   };
   /** It did not match the moment itself: it came to mind with something that did ({@link MemoryPolicy.associate}). */
   linked?: true;
+  /** For what the character believes: how sure it is. */
+  confidence?: MemoryConfidence;
+  /** For what the character believes: something it took in since speaks against it. */
+  disputed?: true;
   /** Why it came back, when the query asked to be told ({@link RecallQuery.explain}). */
   why?: RecallWhy;
 }
@@ -2580,7 +2691,7 @@ interface RecallQuery {
 /** What recall reads: the events a character took in and what it believes. */
 interface RecallSource {
   events: Pick<EventRepository, 'perceivedBy'>;
-  memories: Pick<MemoryRepository, 'list'>;
+  memories: Pick<MemoryRepository, 'list'> & Partial<Pick<MemoryRepository, 'evidenceIndex'>>;
   clock: Pick<ClockRepository, 'get' | 'log'>;
   /** Optional for lightweight callers; a session supplies it so socially charged people are stronger cues. */
   relationships?: Pick<RelationshipRepository, 'from'>;
@@ -2623,6 +2734,8 @@ interface Candidate {
   recalls: number;
   seed: number;
   durability: number;
+  /** For something the character took in that beliefs rest on: those beliefs. */
+  covered?: number[];
 }
 declare function overlap(cues: ReadonlySet<string>, text: string, tags: readonly string[]): number;
 /** One thing a character could be reminded of, with the text to match it against the moment. */
@@ -2646,7 +2759,9 @@ interface RecallEvidence {
   rerank?: ReadonlyMap<string, number>;
 }
 /** Everything the character could be reminded of, for a caller that ranks by meaning (an embedding, a reranker) before asking for the recall. */
-declare function recallCandidates(source: RecallSource, query: Pick<RecallQuery, 'characterId' | 'characters' | 'situation' | 'turn' | 'locationId' | 'about'>): RecallCandidate[];
+declare function recallCandidates(source: RecallSource, query: Pick<RecallQuery, 'characterId' | 'characters' | 'situation' | 'turn' | 'locationId' | 'about'> & {
+  policy?: MemoryPolicy;
+}): RecallCandidate[];
 /** Fuse scores from 0 to 1 into one, per key: the weighted average over the searches that ran (those with any score above 0). */
 declare function fuseScores(searches: readonly {
   weight: number;
@@ -2820,6 +2935,9 @@ interface RecordsView {
     text: string;
     about: string[];
     importance: number;
+    confidence: string;
+    evidence_for: number[];
+    evidence_against: number[];
     turn: number;
   }[];
   open_threads: {
@@ -3008,6 +3126,8 @@ interface SessionStore {
     beats: number;
     cues: number;
   }): TriggerNote[];
+  /** Which of these notes are still to be told, and in what words as the story stands now; the others are withdrawn, with the reason. Nothing is changed. */
+  deliverNotes(notes: readonly TriggerNote[], clock: TriggerClock): Delivery;
   /** Write a consistent copy of the whole database to `path`, which must not exist. */
   snapshotTo(path: string): void;
   close(): void;
@@ -3216,6 +3336,95 @@ declare function createCharacterTools(link: () => AgentLink, characterId: Charac
 /** Why a value is not one the variable can have, or nothing when it is. */
 declare function valueIssue(def: Pick<VariableDefinition, 'key' | 'kind' | 'min' | 'max' | 'integer' | 'options'>, value: unknown): string | undefined;
 //#endregion
+//#region src/records/calendar.d.ts
+/**
+ * Which days a thing applies on, beyond the days of the week: whole months, a date every year or once, a stretch of dates, the day of the month,
+ * the first or last Monday of a month, a season, and the holidays a world names. A day is told by tokens (`dec`, `12-24`, `1912-09-21..1912-09-22`,
+ * `dom:1`, `nth:mon:1`, `season:winter`, `holiday:founders-day`, `fri`); a token with `!` before it is a day it does not apply on. A list holds on a
+ * day when it names no day to apply on or one of them is today, and none of the days to leave out is.
+ */
+declare const MONTH_NAMES: readonly ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+declare const SEASONS: readonly ["spring", "summer", "autumn", "winter"];
+type Season = (typeof SEASONS)[number];
+type Hemisphere = 'north' | 'south';
+/** A day by the wall clock of the story: the month is 1 to 12 and the weekday 0 (Sunday) to 6. */
+interface CalendarDay {
+  year: number;
+  month: number;
+  day: number;
+  weekday: number;
+}
+interface Holiday {
+  id: string;
+  name: string;
+  /** The days it falls on, as tokens other than `holiday:`. */
+  on: string[];
+}
+interface Calendar {
+  hemisphere: Hemisphere;
+  holidays: Holiday[];
+}
+declare const NO_CALENDAR: Calendar;
+type Parsed = {
+  kind: 'weekday';
+  weekday: number;
+} | {
+  kind: 'month';
+  month: number;
+} | {
+  kind: 'date';
+  year?: number;
+  month: number;
+  day: number;
+} | {
+  kind: 'span';
+  from: {
+    year?: number;
+    month: number;
+    day: number;
+  };
+  to: {
+    year?: number;
+    month: number;
+    day: number;
+  };
+} | {
+  kind: 'dom';
+  day: number | 'last';
+} | {
+  kind: 'nth';
+  weekday: number;
+  n: number | 'last';
+} | {
+  kind: 'season';
+  season: Season;
+} | {
+  kind: 'holiday';
+  id: string;
+};
+/** What a token says, or why it says nothing. */
+declare function parseDayToken(raw: string): {
+  token: Parsed;
+  negated: boolean;
+} | {
+  problem: string;
+};
+/** What is wrong with a list of day tokens, each with where it is. `holidays` are those the world names, when `holiday:` may be used. */
+declare function dayTokenProblems(tokens: readonly string[], path: string, holidays?: ReadonlySet<string> | 'any'): string[];
+/** The season a day is in, by the months of its hemisphere (winter is December to February in the north, June to August in the south). */
+declare function seasonOf(day: Pick<CalendarDay, 'month'>, hemisphere?: Hemisphere): Season;
+/** Whether a list of day tokens holds on a day; tokens that say nothing sensible count as not matching. An empty list holds on every day. */
+declare function dayMatches(tokens: readonly string[], day: CalendarDay, calendar?: Calendar): boolean;
+/** The holidays that fall on a day. A holiday is told by days that are no holidays themselves, so that none can lead back to itself. */
+declare function holidaysOn(calendar: Calendar, day: CalendarDay): Holiday[];
+/** The calendar a story was started with, from its metadata; none when the world has none. */
+declare function readCalendar(metadata: {
+  getValue(key: string): unknown;
+}): Calendar;
+declare const writeCalendar: (metadata: {
+  setValue(key: string, value: never): void;
+}, calendar: Calendar) => void;
+//#endregion
 //#region src/records/agenda.d.ts
 /** One occurrence of a routine window: the stretch of time it holds on a particular day. */
 interface Occurrence {
@@ -3226,9 +3435,9 @@ interface Occurrence {
 /** An engagement still pending this long after it was due (or over) is overdue. */
 declare const ENGAGEMENT_GRACE: number;
 /** The window that holds at an instant (the first of the list that does), with the stretch of this occurrence of it. */
-declare function occurrenceAt(windows: readonly StoredRoutineWindow[], now: number, zone: string): Occurrence | undefined;
+declare function occurrenceAt(windows: readonly StoredRoutineWindow[], now: number, zone: string, calendar?: Calendar): Occurrence | undefined;
 /** The window that starts next after an instant, within `horizon`. */
-declare function nextOccurrence(windows: readonly StoredRoutineWindow[], now: number, zone: string, horizon: number): Occurrence | undefined;
+declare function nextOccurrence(windows: readonly StoredRoutineWindow[], now: number, zone: string, horizon: number, calendar?: Calendar): Occurrence | undefined;
 interface RankedGoal {
   intent: CharacterIntent;
   /** The deadline as an instant, when it has one that can be read. */
@@ -3262,6 +3471,9 @@ declare function agendaAt(source: {
   routines: Pick<RoutineRepository, 'list'>;
   engagements: Pick<EngagementRepository, 'list'>;
   intents: Pick<IntentRepository, 'list'>;
+  metadata?: {
+    getValue(key: string): unknown;
+  };
 }, characterId: CharacterId, now: number, zone: string, options?: AgendaOptions): Agenda;
 //#endregion
 //#region src/sqlite/agenda-repositories.d.ts
@@ -3307,16 +3519,16 @@ declare function zonedInstant(fields: {
  * @throws {RangeError} when it is not a date and time.
  */
 declare function parseInstant(text: string, zone: string): number;
-/** `Tuesday 4 October 1912, 21:40`. */
-declare function describeInstant(instant: number, zone: string): string;
+/** `Tuesday 4 October 1912, 21:40`, or `1912年10月4日 星期二 21:40`. */
+declare function describeInstant(instant: number, zone: string, language?: 'en' | 'zh'): string;
 /** `1912-10-04T21:40:00` as the wall clock of a zone reads, the form a file or a person can write back. */
 declare function localIso(instant: number, zone: string): string;
 declare const DAY_PARTS: readonly ["night", "morning", "afternoon", "evening"];
 type DayPart = (typeof DAY_PARTS)[number];
 /** Night is from 22:00 to 05:00, morning to 12:00, afternoon to 17:00, evening after. */
 declare function dayPart(minuteOfDay: number): DayPart;
-/** In words and rounded to what matters: `45 seconds`, `3 hours 12 minutes`, `2 days 3 hours`. */
-declare function describeDuration(milliseconds: number): string;
+/** In words and rounded to what matters: `45 seconds`, `3 hours 12 minutes`, `2 days 3 hours`; or `45秒`, `3小时12分钟`, `2天3小时`. */
+declare function describeDuration(milliseconds: number, language?: 'en' | 'zh'): string;
 /** The minute of the day for `HH:MM` (24-hour), or nothing when it is not one. */
 declare function parseTimeOfDay(text: string): number | undefined;
 /**
@@ -3353,6 +3565,60 @@ declare function addLocalDays(instant: number, zone: string, days: number): {
   weekday: number;
 };
 //#endregion
+//#region src/records/template.d.ts
+/**
+ * What the words of a cue or a beat may name by `{kind:key}`, filled in from the story when they are told. The key is how the world's files
+ * name the thing (`@self` in a cue is the character it is said to), and a name follows the story: a renamed character is renamed in the words.
+ */
+declare const TEMPLATE_KINDS: {
+  /** The name of a character. */
+  readonly character: {
+    readonly args: 1;
+    readonly about: "a character";
+  };
+  /** The name of a place. */
+  readonly place: {
+    readonly args: 1;
+    readonly about: "a place";
+  };
+  /** The name of an item. */
+  readonly item: {
+    readonly args: 1;
+    readonly about: "an item";
+  };
+  /** The name of the place a character is in now. */
+  readonly where: {
+    readonly args: 1;
+    readonly about: "a character";
+  };
+  /** Who holds an item now, or the place it lies in. */
+  readonly holder: {
+    readonly args: 1;
+    readonly about: "an item";
+  };
+  /** What a variable is now, in words: `{value:key}` for a world variable, `{value:key:subject}` for the character, item or place it is about. */
+  readonly value: {
+    readonly args: 2;
+    readonly about: "a variable";
+  };
+  /** The time of day in the story, as `19:30`. */
+  readonly time: {
+    readonly args: 0;
+    readonly about: "";
+  };
+};
+type TemplateKind = keyof typeof TEMPLATE_KINDS;
+interface Placeholder {
+  raw: string;
+  kind: TemplateKind;
+  args: string[];
+}
+/** The placeholders in some words, and what is wrong with any that is not one. Anything that does not look like `{word}` or `{word:key}` is plain text. */
+declare function placeholdersOf(text: string): {
+  found: Placeholder[];
+  problems: string[];
+};
+//#endregion
 //#region src/records/lint.d.ts
 type LintSeverity = 'error' | 'warning' | 'info';
 interface LintFinding {
@@ -3373,5 +3639,5 @@ type LintTarget = Pick<RecordsTarget, 'characters' | 'locations' | 'placements'
  */
 declare function lintWorld(target: LintTarget): LintFinding[];
 //#endregion
-export { ACCURACIES, Accuracy, type Agenda, type AgendaEngagement, type AgendaOptions, type AgentLink, type AgentResolver, type Announcement, type BeliefEdit, CHARACTER_CONTROLS, CHARACTER_KINDS, CHARACTER_ROLES, CHARACTER_TIERS, CLOCK_MODES, COMPARISONS, CONSOLIDATION_KINDS, CONTAINER_STATES, Character, CharacterControl, CharacterDefinition, CharacterFilter, CharacterId, CharacterIntent, CharacterKind, CharacterMemory, CharacterMemoryPatch, type CharacterMove, CharacterPatch, type CharacterRepository, CharacterRole, CharacterSpeech, CharacterStart, CharacterState, CharacterStatePatch, type CharacterStateRepository, CharacterTier, type Clarity, type Clock, ClockMode, ClockState, Comparison, Config, ConflictError, ConsolidationItem, ConsolidationItemId, ConsolidationKind, type ConsolidationRepository, ContainerSpec, ContainerState, CorruptDataError, DAY, DAY_PARTS, DEFAULT_MEMORY_POLICY, DEFAULT_SLOTS, type DayPart, EMOTION_VARIABLES, ENGAGEMENT_GRACE, ENGAGEMENT_STATUSES, EXIT_STATES, type EditChecker, type EditResult, EmbeddingIndexInfo, EmotionStart, EmotionVector, Engagement, EngagementFilter, EngagementId, EngagementPatch, EngagementStatus, EntityKnowledge, type EventEdit, EventId, type EventRepository, Exit, type ExitChange, ExitDefinition, ExitId, ExitOpener, ExitPatch, ExitState, Faction, FactionDefinition, FactionId, FactionIntent, type FactionIntentRepository, FactionMembership, FactionMembershipDefinition, type FactionMembershipRepository, FactionPatch, FactionRelationship, FactionRelationshipDefinition, type FactionRelationshipRepository, type FactionRepository, FactionState, FactionStatePatch, type FactionStateRepository, type FiredTrigger, HOUR, Holder, Holding, IMPORTANCE_MAX, IMPORTANCE_MIN, INTENT_HORIZONS, INTENT_STATUSES, INTENT_TYPES, ITEM_ACTIONS, Intent, IntentFilter, IntentHorizon, IntentId, IntentPatch, type IntentRepository, IntentStatus, IntentType, InvalidEditError, InvalidMoveError, InvalidValueError, Item, type ItemAction, type ItemChange, type ItemChangeSpec, type ItemContext, ItemDefinition, type ItemEditSpec, type ItemEffect, ItemId, ItemPatch, type ItemPlan, type ItemRepository, JsonValue, KNOWLEDGE_KINDS, KnowledgeDefinition, KnowledgeKind, type KnowledgeRepository, type KnownMoveContext, LORE_KINDS, LORE_SUBJECT_KINDS, type LintFinding, type LintSeverity, type LintTarget, type LocalTime, Location, LocationDefinition, LocationFeature, LocationId, LocationPatch, type LocationRepository, Lore, LoreDefinition, LoreId, LoreKind, LorePatch, LoreSubject, LoreSubjectDefinition, LoreSubjectKind, MAX_LOCATION_FEATURES, MAX_ROUTINE_WINDOWS, MAX_SHOWN, MAX_TRIGGERS, MAX_VARIABLES, MEMBERSHIP_STATUSES, MEMORY_KINDS, MIGRATION_BACKUP_FOLDER, MINUTE, MembershipPatch, MembershipStatus, MemoryId, MemoryKind, type MemoryPolicy, type MemoryRepository, type MetadataRepository, Move, type MoveContext, MovePlan, type NewBelief, NewCharacter, NewCharacterMemory, type NewCharacterSpec, NewCharacterState, NewEngagement, type NewEvent, NewExit, type NewExitBetween, type NewExit$1 as NewExitEdit, NewFaction, NewFactionState, NewItem, type NewItemSpec, NewLocation, NewLore, NewPerception, type NewPlace, NewPlacement, NewRelationship, NewSession, NewStoryEvent, NewSummary, NewTriggerNote, NotFoundError, type Occurrence, type OpenOptions, PERCEPTION_MODES, PLACEABLE_KINDS, PLOT_NUDGE_MODES, PLOT_STATUSES, PendingCommit, type PendingCommitRepository, PendingEmbedding, type PerceivedBy, PerceivedEvent, Perception, type PerceptionAddition, type PerceptionEdit, PerceptionId, PerceptionMode, PerceptionPatch, type PlaceEdit, PlaceableKind, Placement, type PlacementRepository, PlotDefinition, PlotDevelopment, PlotNudgeMode, PlotProgress, PlotStatus, RECALL_ITEM_KINDS, type RankedGoal, type RecallCandidate, type RecallEvidence, RecallHit, type RecallIndexRepository, RecallItemKind, type RecallPool, type RecallQuery, type RecallSearch, type RecallSource, type RecallWhy, type Recalled, type RecordsEdit, type RecordsScope, type RecordsTarget, type RecordsView, Relationship, RelationshipDefinition, RelationshipId, RelationshipPatch, type RelationshipRepository, type RelationshipRetraction, type RelationshipSet, RoleplayState, RoutineDefinition, RoutineWindow, type RunResult, LATEST_VERSION as SCHEMA_VERSION, SECOND, SESSION_DATABASE_FILE, SLOT_ID, SUMMARY_LEVELS, SchemaError, type SemanticRanker, type Session, type SessionInit, type SessionListing, SessionMetadata, type SessionStore, type ShownVariable, Slot, type SlotRepository, SocialSubjectKind, type SqlDatabase, type SqlDriver, type SqlValue, StateError, type StatePatch, type StoreOptions, StoredRoutineWindow, StoredVariable, StoryEvent, StoryEventFilter, StoryEventPatch, StoryThread, Summary, SummaryId, SummaryLevel, type SummaryRepository, THREAD_STATUSES, TIME_CHANGE_KINDS, TRIGGER_NOTE_KINDS, TRIGGER_STATUSES, ThreadId, type ThreadRepository, ThreadStatus, TimeChange, TimeChangeFilter, TimeChangeKind, Trigger, TriggerAnnouncement, TriggerAudience, type TriggerClock, TriggerCondition, TriggerDefinition, TriggerEffect, TriggerId, TriggerNote, TriggerNoteKind, type TriggerRun, type TriggerRunOptions, TriggerStatus, VARIABLE_KEY, VARIABLE_KINDS, VARIABLE_SUBJECTS, VARIABLE_VISIBILITIES, VISUAL_SUBJECT_KINDS, type VariableAudience, VariableBand, type VariableChangeSpec, type VariableContext, VariableDefinition, VariableDefinitionInput, type VariableEffect, VariableKind, type VariablePlan, VariableSubject, VariableValue, VariableVisibility, type VectorSearch, type VectorSupport, VisualIdentity, VisualIdentityInput, VisualIdentityPatch, type VisualIdentityRepository, VisualSubjectKind, WEEKDAY_NAMES, WorldReference, addLocalDays, agendaAt, announcements, apply, applyItemPlan, applyRecordsEdit, audienceIds, catchUpPlan, changeItem, changeVariable, characterKey, clarityAt, clockTime, conditionHolds, createCharacterTools, createSession, createSessionStore, createTools, dayPart, deleteSession, denseScore, describeDuration, describeHolder, describeInstant, describeValue, finishRecall, fuseScores, inAudience, inWindow, isSessionId, isTimeZone, itemKey, jitter, judgedStatements, lapseNotes, lintWorld, listSessions, localIso, localTime, locationKey, mentioned, migrationBackupPath, moveCharacter, name, nextOccurrence, nextTimeOfDay, nodeSqliteDriver, occurrenceAt, openSession, openSessionStore, overlap, parseInstant, parseRecordsEdit, parseTimeOfDay, parseTriggerDefinition, planItemChange, planKnownMove, planMove, planVariableChange, poolCandidates, rankGoals, readRecords, readTriggerDefinition, recall, recallCandidates, recallPool, recordsEditSchema, retention, runTriggers, seededRoll, sessionDatabase, sessionFolder, shownVariables, subjectOf, systemClock, systemTimeZone, tokens, triggerReferenceProblems, valueIssue, zonedInstant };
+export { ACCURACIES, Accuracy, type Agenda, type AgendaEngagement, type AgendaOptions, type AgentLink, type AgentResolver, type Announcement, type BeliefEdit, CHARACTER_CONTROLS, CHARACTER_KINDS, CHARACTER_ROLES, CHARACTER_TIERS, CLOCK_MODES, COMPARISONS, CONSOLIDATION_KINDS, CONTAINER_STATES, type Calendar, type CalendarDay, Character, CharacterControl, CharacterDefinition, CharacterFilter, CharacterId, CharacterIntent, CharacterKind, CharacterMemory, CharacterMemoryPatch, type CharacterMove, CharacterPatch, type CharacterRepository, CharacterRole, CharacterSpeech, CharacterStart, CharacterState, CharacterStatePatch, type CharacterStateRepository, CharacterTier, type Clarity, type Clock, ClockMode, ClockState, Comparison, Config, ConflictError, ConsolidationItem, ConsolidationItemId, ConsolidationKind, type ConsolidationRepository, ContainerSpec, ContainerState, CorruptDataError, DAY, DAY_PARTS, DEFAULT_CONFIDENCE, DEFAULT_MEMORY_POLICY, DEFAULT_SLOTS, type DayPart, type Delivery, EMOTION_VARIABLES, ENGAGEMENT_GRACE, ENGAGEMENT_STATUSES, EVIDENCE_RELATIONS, EXIT_STATES, type EditChecker, type EditResult, EmbeddingIndexInfo, EmotionStart, EmotionVector, Engagement, EngagementFilter, EngagementId, EngagementPatch, EngagementStatus, EntityKnowledge, type EventEdit, EventId, type EventRepository, EvidenceRelation, Exit, type ExitChange, ExitDefinition, ExitId, ExitOpener, ExitPatch, ExitState, Faction, FactionDefinition, FactionId, FactionIntent, type FactionIntentRepository, FactionMembership, FactionMembershipDefinition, type FactionMembershipRepository, FactionPatch, FactionRelationship, FactionRelationshipDefinition, type FactionRelationshipRepository, type FactionRepository, FactionState, FactionStatePatch, type FactionStateRepository, type FiredTrigger, HOUR, type Hemisphere, Holder, Holding, type Holiday, IMPORTANCE_MAX, IMPORTANCE_MIN, INTENT_HORIZONS, INTENT_STATUSES, INTENT_TYPES, ITEM_ACTIONS, Intent, IntentFilter, IntentHorizon, IntentId, IntentPatch, type IntentRepository, IntentStatus, IntentType, InvalidEditError, InvalidMoveError, InvalidValueError, Item, type ItemAction, type ItemChange, type ItemChangeSpec, type ItemContext, ItemDefinition, type ItemEditSpec, type ItemEffect, ItemId, ItemPatch, type ItemPlan, type ItemRepository, JsonValue, KNOWLEDGE_KINDS, KnowledgeDefinition, KnowledgeKind, type KnowledgeRepository, type KnownMoveContext, LANGUAGES, LORE_KINDS, LORE_SUBJECT_KINDS, Language, type LintFinding, type LintSeverity, type LintTarget, type LocalTime, Location, LocationDefinition, LocationFeature, LocationId, LocationPatch, type LocationRepository, Lore, LoreDefinition, LoreId, LoreKind, LorePatch, LoreSubject, LoreSubjectDefinition, LoreSubjectKind, MAX_LOCATION_FEATURES, MAX_ROUTINE_WINDOWS, MAX_SHOWN, MAX_TRIGGERS, MAX_VARIABLES, MEMBERSHIP_STATUSES, MEMORY_CONFIDENCES, MEMORY_KINDS, MIGRATION_BACKUP_FOLDER, MINUTE, MONTH_NAMES, MembershipPatch, MembershipStatus, MemoryConfidence, MemoryEvidence, MemoryId, MemoryKind, type MemoryPolicy, type MemoryRepository, MessageValues, type MetadataRepository, Move, type MoveContext, MovePlan, NO_CALENDAR, type NewBelief, NewCharacter, NewCharacterMemory, type NewCharacterSpec, NewCharacterState, NewEngagement, type NewEvent, NewExit, type NewExitBetween, type NewExit$1 as NewExitEdit, NewFaction, NewFactionState, NewItem, type NewItemSpec, NewLocation, NewLore, NewPerception, type NewPlace, NewPlacement, NewRelationship, NewSession, NewStoryEvent, NewSummary, NewTriggerNote, NotFoundError, type Occurrence, type OpenOptions, PERCEPTION_MODES, PLACEABLE_KINDS, PLOT_NUDGE_MODES, PLOT_STATUSES, PendingCommit, type PendingCommitRepository, PendingEmbedding, type PerceivedBy, PerceivedEvent, Perception, type PerceptionAddition, type PerceptionEdit, PerceptionId, PerceptionMode, PerceptionPatch, type PlaceEdit, PlaceableKind, type Placeholder, Placement, type PlacementRepository, PlotDefinition, PlotDevelopment, PlotNudgeMode, PlotProgress, PlotStatus, RECALL_ITEM_KINDS, type RankedGoal, type RecallCandidate, type RecallEvidence, RecallHit, type RecallIndexRepository, RecallItemKind, type RecallPool, type RecallQuery, type RecallSearch, type RecallSource, type RecallWhy, type Recalled, type RecordsEdit, type RecordsScope, type RecordsTarget, type RecordsView, Relationship, RelationshipDefinition, RelationshipId, RelationshipPatch, type RelationshipRepository, type RelationshipRetraction, type RelationshipSet, RoleplayState, RoutineDefinition, RoutineWindow, type RunResult, LATEST_VERSION as SCHEMA_VERSION, SEASONS, SECOND, SELF, SESSION_DATABASE_FILE, SLOT_ID, SUMMARY_LEVELS, SchemaError, type Season, type SemanticRanker, type Session, type SessionInit, type SessionListing, SessionMetadata, type SessionStore, type ShownVariable, Slot, type SlotRepository, SocialSubjectKind, type SqlDatabase, type SqlDriver, type SqlValue, StateError, type StatePatch, type StoreOptions, StoredRoutineWindow, StoredVariable, StoryEvent, StoryEventFilter, StoryEventPatch, StoryThread, Summary, SummaryId, SummaryLevel, type SummaryRepository, TEMPLATE_KINDS, THREAD_STATUSES, TIME_CHANGE_KINDS, TRIGGER_NOTE_KINDS, TRIGGER_STATUSES, type TemplateKind, ThreadId, type ThreadRepository, ThreadStatus, TimeChange, TimeChangeFilter, TimeChangeKind, Translate, Trigger, TriggerAnnouncement, TriggerAudience, type TriggerClock, TriggerCondition, TriggerDefinition, TriggerEffect, TriggerId, TriggerNote, TriggerNoteKind, type TriggerRun, type TriggerRunOptions, TriggerStatus, UnwritableError, VARIABLE_KEY, VARIABLE_KINDS, VARIABLE_SUBJECTS, VARIABLE_VISIBILITIES, VISUAL_SUBJECT_KINDS, type VariableAudience, VariableBand, type VariableChangeSpec, type VariableContext, VariableDefinition, VariableDefinitionInput, type VariableEffect, VariableKind, type VariablePlan, VariableSubject, VariableValue, VariableVisibility, type VectorSearch, type VectorSupport, VisualIdentity, VisualIdentityInput, VisualIdentityPatch, type VisualIdentityRepository, VisualSubjectKind, WEEKDAY_NAMES, WorldReference, addLocalDays, agendaAt, announcements, apply, applyItemPlan, applyRecordsEdit, audienceIds, catchUpPlan, changeItem, changeVariable, characterKey, clarityAt, clockTime, conditionHolds, createCharacterTools, createSession, createSessionStore, createTools, dayMatches, dayPart, dayTokenProblems, deleteSession, deliverNotes, denseScore, describeDuration, describeHolder, describeInstant, describeValue, finishRecall, fuseScores, holidaysOn, inAudience, inWindow, isSessionId, isTimeZone, itemKey, jitter, judgedStatements, languageOf, lapseNotes, lintWorld, listSessions, localIso, localTime, locationKey, mentioned, migrationBackupPath, moveCharacter, name, nextOccurrence, nextTimeOfDay, nodeSqliteDriver, occurrenceAt, openSession, openSessionStore, overlap, parseDayToken, parseInstant, parseRecordsEdit, parseTimeOfDay, parseTriggerDefinition, placeholdersOf, planItemChange, planKnownMove, planMove, planVariableChange, poolCandidates, rankGoals, readCalendar, readRecords, readTriggerDefinition, recall, recallCandidates, recallPool, recordsEditSchema, renderWords, retention, runTriggers, seasonOf, seededRoll, sessionDatabase, sessionFolder, shownVariables, subjectOf, systemClock, systemTimeZone, tokens, translated, translation, translator, triggerReferenceProblems, valueIssue, writeCalendar, zonedInstant };
 //# sourceMappingURL=index.d.ts.map