Example

What the reader already knows, as narrowly as it can be said

Grade knowledge from dated evidence, keep a familiar term in a different sense out of the known pile, and see the two conditions a unit must meet before it can be left out.

“Don’t tell me what I already know” is a rule that needs a narrow answer to two questions: how do you know what someone knows, and what does “already” mean across sources? The chapter’s answer is that a fact is about a concept in a sense — the meaning this source gives it — with dated evidence, and that the grade is derived from the evidence rather than stored as a property of the person.

Run it

git clone https://github.com/ernanhughes/project-language.git
cd project-language
git checkout 329660f679a5a87831f91fe1430c20ac9360dda8
npm ci
npm run example:talk

The same program as Chapters 14 and 15. The knowledge state is a value passed in; it is not persisted and not a model of the person.

Expected outcome

The state is shown with the evidence behind it:

...
Iris's state, as the system would show it to her:
  partial synchrony (the delay bound exists but is unknown): KNOWN — used_correctly on 2025-05-02
  quorum (a majority of the nodes): KNOWN — stated on 2024-11-20

A term the person has met in a different sense is not a known meaning, so the unit stays; a term known in this sense, with nothing depending on it, can go:

...
Iris: units shown, and what may be left out:
  KEEP     u-sync-sense  partial synchrony: the term is familiar (KNOWN in the sense "the delay bound exists but is unknown") but this source uses it in the sense "the delay bound is known to the protocol"
  OMIT     u-quorum      quorum (a majority of the nodes) is known (stated on 2024-11-20) and nothing shown depends on it

And the run states the reason in a sentence:

...
The word 'partial synchrony' is familiar to Iris, and the speaker uses it in a narrower sense, so it stays. A word is not a meaning.

A grade is derived, never stored

The evidence policy is declared, and the grade is computed from dated evidence at a given time. Exposure is not evidence of knowing:

export type Grade = "KNOWN" | "PARTIAL" | "UNKNOWN";
export const EVIDENCE_KINDS = ["stated", "used_correctly", "answered", "asked_explanation", "corrected_system", "worked_with", "exposed", "mistake"] as const;
export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];

/** Declared policy, in order of strength. Days are how long the evidence is trusted at full strength; after that it counts one grade lower. */
export const EVIDENCE_POLICY: Readonly<Record<Exclude<EvidenceKind, "mistake">, { strength: Grade; trusted_days: number }>> = {
  stated:            { strength: "KNOWN",   trusted_days: 730 },
  used_correctly:    { strength: "KNOWN",   trusted_days: 730 },
  answered:          { strength: "KNOWN",   trusted_days: 365 },
  corrected_system:  { strength: "KNOWN",   trusted_days: 730 },
  worked_with:       { strength: "PARTIAL", trusted_days: 365 },
  asked_explanation: { strength: "PARTIAL", trusted_days: 180 },
  exposed:           { strength: "UNKNOWN", trusted_days: 0 },
};

A familiar term in another sense is not a known meaning:

export function knows(state: KnowledgeState, concept: string, sense: string, now: string): Knows {
  const same = state.find(f => f.concept === concept && f.sense === sense);
  if (same) return { ...gradeOf(same, now), sense_mismatch: false };
  const other = state.find(f => f.concept === concept);
  if (other) {
    const g = gradeOf(other, now);
    return { grade: "UNKNOWN", sense_mismatch: true, known_sense: other.sense, why: `the term is familiar (${g.grade} in the sense "${other.sense}") but this source uses it in the sense "${sense}"` };
  }
  return { grade: "UNKNOWN", why: "not observed; that is not the same as not known", sense_mismatch: false };
}

And omission needs both conditions — known in this sense and not needed by anything shown. Partial knowledge collapses the unit rather than removing it, because hiding a needed thing can strand the reader:

export function omissionPlan(
  candidates: readonly Unit[], shownIds: readonly string[], allUnits: readonly Unit[],
  uses: readonly ConceptUse[], state: KnowledgeState, now: string,
): OmissionDecision[] {
  return candidates.map(u => {
    const dependedOn = allUnits.filter(x => shownIds.includes(x.id) && x.id !== u.id && x.dependsOn.includes(u.id)).map(x => x.id);
    const use = uses.find(c => c.unit_id === u.id);
    if (!use) return { unit_id: u.id, treatment: "keep", why: "no concept is recorded for this unit; nothing says it is known", sense_mismatch: false };
    const k = knows(state, use.concept, use.sense, now);
    if (dependedOn.length) return { unit_id: u.id, treatment: "keep", why: `${use.concept}: ${k.grade}, but ${dependedOn.join(", ")} depend${dependedOn.length === 1 ? "s" : ""} on it; known is not safe to omit`, sense_mismatch: k.sense_mismatch };
    if (k.grade === "KNOWN") return { unit_id: u.id, treatment: "omit", why: `${use.concept} (${use.sense}) is known (${k.why}) and nothing shown depends on it`, sense_mismatch: false };
    if (k.grade === "PARTIAL") return { unit_id: u.id, treatment: "collapse", why: `${use.concept} is partly known (${k.why}); offered collapsed, not removed`, sense_mismatch: false };
    return { unit_id: u.id, treatment: "keep", why: `${use.concept}: ${k.why}`, sense_mismatch: k.sense_mismatch };
  });
}

Mechanism and limitations

Documented: the vocabulary of the module’s own header comment — not observed != not known, mentioned or exposed != mastered, familiar term != known meaning — and the rule that omission needs both conditions, are in core/radar/src/attention/knowledge.ts.

Observed: the run above. Iris’s two concepts graded KNOWN with their evidence and dates; partial synchrony was kept because the source uses it in a narrower sense than the one she knows; quorum was omitted because it is known in this sense and nothing shown depends on it. Mina’s quorum was not omitted — only exposed is not known.

Not shown. The knowledge state is a value passed in: it is not persisted, it is not kept between sessions, and it is not a model of who the person is. The evidence is written by hand. The policy is declared, not measured: how long a grade is trusted is a choice, and the day counts are not derived from anything. Nothing here measures whether omitting what someone knows actually helps them.

Canonical source and the knowledge module .

Understand this example

Copy this prompt into your AI tool. No code runs here.

Apply this example

Copy this prompt into your AI tool. No code runs here.