cogmemory 0.0.1-beta.2

package/src/cognitive/relevance.ts

@@ -0,0 +1,199 @@
+/**
+ * Deterministic text, relevance and reconciliation primitives.
+ *
+ * The whole decision layer of a memory system, with no model, no database and
+ * no dependencies — so the service, an in-process runtime, and a test all make
+ * the same calls. The reasoning behind each threshold is written down because
+ * the numbers are only defensible with it:
+ *
+ * - A memory cannot be found by a model being smart, only by words overlapping.
+ * - Lexical overlap peaks on identical strings and bottoms out on the
+ *   paraphrases that actually add information, so the *recall* floor is low and
+ *   a separate step decides what to do with what came back.
+ * - Losing a fact is permanent; an extra duplicate costs one row. Every
+ *   threshold below leans that way.
+ */
+
+const STOP_WORDS = new Set([
+  "the", "and", "for", "this", "that", "with", "from", "you", "are", "was", "has", "have",
+  "what", "which", "when", "were", "will", "your", "our", "its", "not", "but", "all", "any",
+  "can", "did", "does", "how", "into", "out", "use", "used", "using", "one", "two", "get",
+  "new", "now", "then", "than", "them", "they", "his", "her", "she", "him", "been", "being",
+  "there", "here", "also", "just", "like", "make", "made", "need", "want", "about", "after",
+  "tell", "know", "give", "show", "please", "would", "could", "should", "shall"
+])
+
+/** Words that appear in every restatement of a fact and so carry no identity. */
+const FILLER_TOKENS = new Set([
+  "this", "that", "these", "those", "there", "here", "with", "from", "into", "must",
+  "should", "always", "never", "under", "over", "about", "after", "before", "when",
+  "where", "which", "what", "your", "their", "them", "they", "then", "than", "also",
+  "just", "only", "each", "every", "some", "such", "very", "more", "most", "same",
+  "file", "files", "name", "names", "project", "repository", "repo", "note"
+])
+
+/** Content words worth matching a memory against. */
+export const relevanceTokens = (value: string): Set<string> =>
+  new Set(
+    value
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((word) => word.length >= 3 && !STOP_WORDS.has(word))
+  )
+
+/** Overlap of two token sets, normalised by the smaller side. */
+export const overlapScore = (query: Set<string>, candidate: Set<string>): number => {
+  if (query.size === 0 || candidate.size === 0) return 0
+  let shared = 0
+  for (const word of query) if (candidate.has(word)) shared += 1
+  return shared / Math.min(query.size, candidate.size)
+}
+
+/**
+ * Floor for *candidate* recall, not a similarity decision.
+ *
+ * Deliberately low. This only decides who gets adjudicated; a tight gate misses
+ * exactly the paraphrases worth merging.
+ */
+export const CANDIDATE_FLOOR = 0.3
+
+/** Above this, a memory is worth promoting into the pre-staged index. */
+export const PROMOTE_THRESHOLD = 0.12
+
+/** How many existing memories to put in front of an adjudicator. */
+export const MAX_CANDIDATES = 8
+
+/** Two results this similar are the same memory, restated. */
+export const COLLAPSE_THRESHOLD = 0.8
+
+/**
+ * Tokens that carry a fact's identity: identifiers, numbers, codes.
+ *
+ * Function words and generic nouns are dropped because they recur in every
+ * restatement and hide real differences.
+ */
+export const distinctiveTokens = (value: string): Set<string> =>
+  new Set(
+    value
+      .toLowerCase()
+      .replace(/['']/g, "")
+      .split(/[^a-z0-9]+/)
+      .filter(Boolean)
+      .filter((w) => /\d/.test(w) || w.length >= 4)
+      .filter((w) => !FILLER_TOKENS.has(w))
+  )
+
+/**
+ * Whether rewriting `original` as `replacement` would drop information.
+ *
+ * Distinctive tokens carry a fact's identity, so a replacement missing one has
+ * deleted something — usually the qualifier that made the two statements differ
+ * at all ("never production", a build id, a port). Trailing plurals are folded
+ * so "deploys" merging into "deploy" is not read as a deletion.
+ *
+ * Biased towards reporting a loss: a false positive costs a duplicate entry,
+ * which is recoverable, while a false negative deletes a fact for good.
+ */
+export const isLossyRewrite = (original: string, replacement: string): boolean => {
+  const fold = (tokens: Set<string>): Set<string> =>
+    new Set([...tokens].map((t) => (t.length >= 4 && t.endsWith("s") ? t.slice(0, -1) : t)))
+  const after = fold(distinctiveTokens(replacement))
+  for (const token of fold(distinctiveTokens(original))) {
+    if (!after.has(token)) return true
+  }
+  return false
+}
+
+/**
+ * Dotted names that are not prose: hostnames, package names, file names.
+ *
+ * `internal-hbr-2291.pineapple.example` is precisely the kind of value a user
+ * names and a memory holds, and without this the identifier patterns below missed
+ * it — the trigger silently never fired for a host, which is one of the cases it
+ * exists for. The last label must be alphabetic, which is what keeps version
+ * strings and abbreviations out; a short stoplist covers the rest.
+ */
+const HOSTNAME = /\b[a-z0-9][a-z0-9-]{1,}(?:\.[a-z0-9-]+)*\.[a-z]{2,}\b/gi
+
+/** Dotted tokens that are ordinary writing, not names. */
+const NOT_A_HOSTNAME = new Set([
+  "eg", "ie", "etc", "vs", "approx", "inc", "ltd", "corp", "dept", "est", "fig", "no", "al"
+])
+
+/**
+ * Identifiers worth matching a memory against: URLs, paths, hostnames,
+ * SCREAMING_SNAKE, camelCase, long kebab-case and hex-ish codes.
+ *
+ * The same idea as Aider's `mentioned_idents`: a user naming a concrete thing
+ * is a much stronger signal than the words around it. This is what turns a
+ * recall into a full-body injection without asking a model.
+ */
+export const extractIdentifiers = (text: string): string[] => {
+  const found = new Set<string>()
+  for (const match of text.match(/\bhttps?:\/\/[^\s<>()[\]"'`]+/g) ?? []) found.add(match)
+  for (const match of text.match(HOSTNAME) ?? []) {
+    if (NOT_A_HOSTNAME.has(match.toLowerCase())) continue
+    found.add(match)
+  }
+  for (const match of text.match(/\b(?:\.{0,2}\/)?[\w-]+(?:\/[\w.-]+)+\/?/g) ?? []) {
+    if (match.length > 3) found.add(match)
+  }
+  for (const match of text.match(/\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b/g) ?? []) found.add(match)
+  for (const match of text.match(/\b[A-Z]{2,}[0-9][A-Z0-9-]*\b/g) ?? []) found.add(match)
+  for (const match of text.match(/\b[a-z]+(?:[A-Z][a-z0-9]+){1,}\b/g) ?? []) found.add(match)
+  for (const match of text.match(/\b[a-z]+(?:-[a-z0-9]+){2,}\b/g) ?? []) found.add(match)
+  for (const match of text.match(/\b[0-9a-f]{6,}\b/gi) ?? []) found.add(match)
+  return [...found]
+}
+
+/**
+ * Instructions about *this conversation* rather than durable facts about the
+ * project.
+ *
+ * "Do not verify the staging build against the repository" and "just remember
+ * this" describe how to behave right now, so storing them produces noise that
+ * later looks like a project constraint.
+ *
+ * Explicit patterns rather than a "is this specific enough?" heuristic, because
+ * over-filtering would silently lose real memories, which is the worse failure.
+ */
+const INTERACTION_SCOPED = [
+  /\b(?:do not|don'?t|never|no need to)\s+(?:verify|check|confirm|look\s?up|search|investigate|browse|resolve)\b/i,
+  /\bjust\s+(?:remember|note|acknowledge|retain|treat)\b/i,
+  /\b(?:held|noted|stored|remembered)\s+(?:in|for)\s+(?:this|the)\s+conversation\b/i,
+  /\bnot\s+verified\b/i,
+  /\bwithout\s+verifying\b/i,
+  /\bfor\s+this\s+(?:conversation|session|turn|reply|response)\s+only\b/i,
+  /^(?:ok|okay|noted|got it|sure|thanks)\b[.!]?$/i
+]
+
+export const isInteractionScoped = (content: string): boolean =>
+  INTERACTION_SCOPED.some((pattern) => pattern.test(content))
+
+/** Similarity of two statements by the tokens that carry identity. */
+export const similarity = (a: string, b: string): number => {
+  const left = distinctiveTokens(a)
+  const right = distinctiveTokens(b)
+  if (left.size === 0 || right.size === 0) return 0
+  let shared = 0
+  for (const word of left) if (right.has(word)) shared += 1
+  return shared / Math.min(left.size, right.size)
+}
+
+export const normalise = (value: string): string => value.trim().toLowerCase()
+
+/** Approximate token cost of a string. */
+export const estimateTokens = (value: string): number => Math.ceil(value.length / 4)
+
+/**
+ * The index line: short, scannable, no body.
+ *
+ * Falling back to the first sentence keeps an index line readable when a memory
+ * arrives from the API without a gist.
+ */
+export const gistOf = (item: { readonly content: string; readonly gist?: string | undefined }): string => {
+  if (item.gist && item.gist.trim().length > 0) return item.gist.trim()
+  const first = item.content.split(/(?<=[.!?])\s/)[0] ?? item.content
+  const trimmed = first.trim()
+  return trimmed.length > 90 ? `${trimmed.slice(0, 90)}…` : trimmed
+}

package/src/cognitive/rules.ts

@@ -0,0 +1,127 @@
+/**
+ * Deterministic fact extraction.
+ *
+ * A model extractor is good at judgement but it is still a model: it can
+ * refuse, hedge, or return nothing, and a fact the user plainly stated then
+ * never gets learned. Everything stated unambiguously is captured here with
+ * plain pattern matching, and the model is layered on top for the subtler cases.
+ *
+ * Only high-confidence shapes are matched. Being wrong in this direction writes
+ * a useless memory; being silent loses a real one, which is the worse failure.
+ */
+
+const URL = /\bhttps?:\/\/[^\s<>()[\]"'`]+/g
+
+/**
+ * Positive requirements only.
+ *
+ * "never X" reads correctly as a requirement. "do not X" / "don't X" must NOT be
+ * captured here: naively taking the object of a negation produces nonsense like
+ * "The user requires: verify it against the repo" from "do not verify it against
+ * the repo", which inverts the meaning.
+ */
+const REQUIREMENT =
+  /\b(always|never|must|should|make sure to|remember to)\b[\s:]+([^.?!\n]{4,160})/gi
+
+/**
+ * "<subject> is <value>".
+ *
+ * The value must NOT stop at the first `.`: that truncates
+ * `internal-hbr-2291.pineapple.example` to `internal-hbr-2291` and then poisons
+ * recall with the broken value. Stop at a period only when it ends a sentence.
+ */
+const ASSIGNMENT = /\b([A-Za-z][\w ()-]{2,60}?)\s+(?:is|are)\s+([^\n?!]{3,200})/g
+
+const CODEISH = /[A-Z0-9_./:-]/
+
+const looksLikeValue = (value: string): boolean => {
+  const trimmed = value.trim()
+  if (trimmed.length < 3 || trimmed.length > 200) return false
+  if (/^(not|nothing|unclear|unknown|the same|that|this|it)\b/i.test(trimmed)) return false
+  return CODEISH.test(trimmed)
+}
+
+/** Cut a captured clause back to its first complete sentence. */
+const firstSentence = (value: string): string => {
+  const match = /\.(?=\s+[A-Z(])/.exec(value)
+  return match ? value.slice(0, match.index) : value
+}
+
+const tidy = (value: string): string =>
+  firstSentence(value)
+    .replace(/\s+/g, " ")
+    .replace(/^(?:that|the|a|an|it|this)\s+/i, "")
+    .replace(/[,;:\s.。]+$/, "")
+    .trim()
+
+export interface DeterministicMemory {
+  readonly content: string
+  readonly domains: Array<string>
+}
+
+/**
+ * Extract statements the user made that are worth remembering, without a model.
+ */
+export const extractDeterministic = (userMessage: string): Array<DeterministicMemory> => {
+  const out: Array<DeterministicMemory> = []
+  const push = (content: string): void => {
+    const cleaned = tidy(content)
+    if (cleaned.length < 8 || cleaned.length > 300) return
+    if (/^(yes|no|ok|okay|sure|thanks|thank you|got it|noted)\b/i.test(cleaned)) return
+    if (out.some((existing) => existing.content.toLowerCase() === cleaned.toLowerCase())) return
+    out.push({ content: cleaned, domains: [] })
+  }
+
+  // 1. URLs are unambiguous.
+  for (const match of userMessage.match(URL) ?? []) {
+    push(`User-provided URL: ${match}`)
+  }
+
+  // 2. Stated requirements, kept in the user's own words.
+  //    Paraphrasing flipped meaning once: "Never force push" became
+  //    "The user requires: force push" — the exact opposite instruction.
+  for (const match of userMessage.matchAll(REQUIREMENT)) {
+    const verb = (match[1] ?? "").toLowerCase()
+    const body = tidy(match[2] ?? "")
+    if (!body) continue
+    push(`User requirement (${verb}): ${body}`)
+  }
+
+  // 3. "X is Y" where Y is identifier-shaped.
+  for (const match of userMessage.matchAll(ASSIGNMENT)) {
+    const subject = tidy(match[1] ?? "")
+    const value = tidy(match[2] ?? "")
+    if (!subject || !looksLikeValue(value)) continue
+    push(`${subject} is ${value}`)
+  }
+
+  // The three passes overlap: "Always run the canary pipeline for staging" gets
+  // caught as a requirement *and* as an assignment, and the assignment copy is
+  // truncated mid-value. Two rows for one sentence is noise the engine then has
+  // to reconcile later, so the contained one is dropped here instead.
+  const deduped = out.filter(
+    (candidate, index) =>
+      !out.some((other, otherIndex) => {
+        if (otherIndex === index) return false
+        if (other.content.length <= candidate.content.length) return false
+        return isCoveredBy(candidate.content, other.content)
+      })
+  )
+
+  return deduped.slice(0, 6)
+}
+
+/**
+ * Whether everything worth keeping in `narrow` is already in `wide`.
+ *
+ * Compared on the tokens that carry a fact's identity, so dropping a number or a
+ * qualifier counts as loss even when the wording differs.
+ */
+const isCoveredBy = (narrow: string, wide: string): boolean => {
+  const have = new Set(wide.toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length >= 4))
+  const covered = narrow
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((word) => word.length >= 4)
+  return covered.length > 0 && covered.every((word) => have.has(word))
+}

package/src/cognitive/types.ts

@@ -0,0 +1,232 @@
+/**
+ * Cognitive Memory types and contracts for not-another-harness.
+ */
+
+export type MemoryTier = "L0" | "L1" | "L2" | "L3";
+
+export type TensionStatus = "active" | "latent" | "resolved";
+
+export type TensionImpact = "low" | "medium" | "critical";
+
+export interface KnowledgeTension {
+  id: string;
+  status: TensionStatus;
+  claimA: {
+    source: string;
+    statement: string;
+    timestamp: number;
+  };
+  claimB: {
+    source: string;
+    statement: string;
+    timestamp: number;
+  };
+  impact: TensionImpact;
+  taskRelevance: number; // 0.0 - 1.0
+  actionableQuestion: string;
+  resolution?: {
+    resolvedAt: number;
+    resolvedBy: string;
+    pattern: string;
+  };
+}
+
+export interface DomainCapability {
+  reliabilityScore: number; // 0.0 - 1.0 (historical success rate)
+  sampleCount: number;
+  knownFailurePatterns: string[];
+  recommendedStrategies: string[];
+}
+
+export interface ProprioceptiveSelfModel {
+  /** Map of domain tag (e.g. "auth", "db-migration", "css") to capability stats */
+  domains: Record<string, DomainCapability>;
+  /** Overall calibration score (1.0 = well-calibrated, <0.7 = overconfident) */
+  calibrationFactor: number;
+  /** Active domains detected in current work */
+  activeDomains: string[];
+}
+
+export interface MemoryMetadata {
+  domains: string[];
+  isFailurePattern?: boolean;
+  isSuccessfulStrategy?: boolean;
+  isGuardrail?: boolean;
+  sourceSessionId?: string;
+  createdAt: number;
+  lastAccessedAt: number;
+  accessCount: number;
+}
+
+export interface MemoryItem {
+  id: string;
+  content: string;
+  /** Dense 1-2 sentence representation for fast arbiter scanning */
+  bookmark: string;
+  /**
+   * Short label shown in the pre-staged index (Claude Code's `MEMORY.md` pattern:
+   * the index is always in context, the body is fetched on demand). Falls back to
+   * a truncation of `content` when the extractor did not supply one.
+   */
+  gist?: string;
+  /** Dense embedding vector (empty array if embedding disabled) */
+  embedding?: number[];
+  tier: MemoryTier;
+  metadata: MemoryMetadata;
+}
+
+/** Why a memory ended up in the prompt — the thing you tune once you log it. */
+/** What to do with a candidate memory once compared against what we hold. */
+export type MemoryReconciliation = {
+  /**
+   * `add` keeps it as a new memory and is the safe default when unsure: an
+   * unmerged duplicate costs a row, while a wrong merge corrupts what we believe.
+   * `merge` collapses a restatement into the existing entry, keeping whichever
+   * carries more information. `replace` supersedes the existing entry. `reject`
+   * drops it as not worth storing.
+   */
+  action: "add" | "merge" | "replace" | "reject";
+  /** Content to store when merging or replacing; defaults to the candidate. */
+  content?: string;
+  /** Why, so a bad merge is diagnosable rather than mysterious. */
+  reason?: string;
+};
+
+
+export type MemoryInclusionReason =
+  /** Shown in the always-present index as a gist only. */
+  | "index"
+  /** Unseen identifier in the user's message matched this memory: body included. */
+  | "trigger"
+  /** Active knowledge tension: body included. */
+  | "tension"
+  /** Proprioceptive guardrail: body included. */
+  | "guardrail";
+
+export interface MemoryInjectionEntry {
+  id: string;
+  tier: MemoryTier;
+  reason: MemoryInclusionReason;
+  /** Index line only. */
+  gist: string;
+  /** Present only when the body was worth the tokens. */
+  body?: string;
+  /** Rough token cost of what was included. */
+  tokens: number;
+}
+
+/** What was put in the prompt this turn, and why. */
+export interface MemoryInjectionReport {
+  text: string;
+  entries: MemoryInjectionEntry[];
+  totalTokens: number;
+  /** True when the total budget forced something out. */
+  truncated: boolean;
+}
+
+export interface TrajectoryPrediction {
+  predictedDomains: string[];
+  predictedFiles: string[];
+  prefetchMemoryIds: string[];
+  confidence: number;
+}
+
+export interface ArbiterEvaluationResult {
+  promotions: Array<{
+    memoryId: string;
+    targetTier: "L1";
+    signalType: "anticipatory" | "tension" | "proprioceptive" | "recency";
+    urgency: number; // 0.0 - 1.0
+  }>;
+  demotions: Array<{
+    memoryId: string;
+    targetTier: "L2";
+    reason: string;
+  }>;
+  pins: Array<{
+    memoryId: string;
+    targetTier: "L0";
+    reason: string;
+  }>;
+  detectedTensions: Array<{
+    claimA: string;
+    claimB: string;
+    impact: TensionImpact;
+    actionableQuestion: string;
+  }>;
+  trajectoryPrediction?: TrajectoryPrediction;
+  selfModelUpdate?: {
+    domain: string;
+    success?: boolean;
+    failurePatternObserved?: string;
+  };
+}
+
+export type ArbiterFn = (params: {
+  turnText: string;
+  assistantReply: string;
+  l0Prompt: string;
+  l1Summaries: Array<{ id: string; bookmark: string; domains: string[] }>;
+  candidates: Array<{ id: string; bookmark: string; domains: string[]; hasTension?: boolean }>;
+}) => Promise<ArbiterEvaluationResult>;
+
+export interface CognitiveMemoryOptions {
+  /** Maximum token budget for L0 (default: 2000) */
+  maxL0Tokens?: number;
+  /** Maximum token budget for L1 hot cache (default: 8000) */
+  maxL1Tokens?: number;
+  /** Ceiling on everything injected into a single prompt (index + bodies). Default 2000. */
+  maxTotalTokens?: number;
+  /** Custom Arbiter evaluator function (e.g. powered by Jev, Gemini Flash, or local model) */
+  arbiter?: ArbiterFn;
+  /** Initial self-model */
+  initialSelfModel?: Partial<ProprioceptiveSelfModel>;
+  /** Auto-extract candidate items from completed turns (default: true) */
+  autoExtractMemories?: boolean;
+  /**
+   * Adjudicate a candidate memory against ones that already exist.
+   *
+   * Lexical overlap cannot make this call: it peaks on identical strings and
+   * bottoms out on the paraphrases that actually add information. Every mature
+   * memory system therefore recalls candidates cheaply and then asks a model,
+   * explicitly allowing "no match". `remember` is the low-bar candidate
+   * recall; `decide` is the precision step.
+   */
+  reconcile?: (input: {
+    /** Every candidate from this turn that resembles something we hold. */
+    items: Array<{ candidate: string; remember: string[] }>;
+  }) => Promise<MemoryReconciliation[]>;
+  /**
+   * Model-backed turn extractor. Preferred over the built-in regex, which only
+   * recognises "always/never/make sure to/remember to" and therefore never
+   * learned ordinary project facts. Return an empty array to learn nothing.
+   */
+  extract?: (turn: { userMessage: string; assistantResponse: string }) => Promise<{
+    memories: Array<{ content: string; domains?: string[] }>;
+    tensions?: Array<{
+      claimA: string;
+      claimB: string;
+      impact: "low" | "medium" | "critical";
+      actionableQuestion: string;
+    }>;
+  }>;
+  /** Persistence callback to save L2/L3 state */
+  onPersist?: (state: CognitiveMemoryStateSnapshot) => Promise<void> | void;
+}
+
+export interface CognitiveMemoryStateSnapshot {
+  l0: {
+    tensions: KnowledgeTension[];
+    selfModel: ProprioceptiveSelfModel;
+    activeTaskTrace: string;
+  };
+  l1: MemoryItem[];
+  l2: MemoryItem[];
+  l3: MemoryItem[];
+  stats: {
+    totalTurnsProcessed: number;
+    predictionsHit: number;
+    predictionsTotal: number;
+    tensionsDetected: number;
+  };
+}

package/src/errors.ts

@@ -0,0 +1,85 @@
+import type { CognitiveMemoryErrorBody } from "./types"
+
+/**
+ * One error class for every failure the service can produce.
+ *
+ * The service already returns a structured envelope — a tag, a message, the
+ * scope that was missing, the fields that failed validation — so the SDK's job is
+ * to hand that over as a typed object instead of making callers dig through
+ * `error.response.data`.
+ *
+ * The predicate methods exist so callers ask semantic questions. `status === 403`
+ * scatters a magic number through every integration and means something slightly
+ * different at each one; `isScopeError()` means the same thing everywhere.
+ */
+export class CognitiveMemoryError extends Error {
+  /**
+   * Set as a real value, because a minifier renames the class and that silently
+   * changes what monitoring groups on. `error.name` is correct either way — the
+   * constructor assigns it — but `SomeError.name` and `error.constructor.name`
+   * are how a reporter identifies a class, and a minified `"h"` breaks that.
+   */
+  static override readonly name = "CognitiveMemoryError"
+
+  /** The service's own tag: `Unauthorized`, `Forbidden`, `InvalidRequest`, … */
+  readonly code: string
+  readonly status: number
+  /** Present on a 403: the scope the key would have needed. */
+  readonly requiredScope?: string
+  /** Present on a 400: which field, and why. */
+  readonly issues?: string[]
+  readonly body?: CognitiveMemoryErrorBody
+
+  constructor(
+    message: string,
+    init: {
+      status: number
+      code: string
+      body?: CognitiveMemoryErrorBody
+      requiredScope?: string
+      issues?: string[]
+    }
+  ) {
+    super(message)
+    this.name = "CognitiveMemoryError"
+    this.status = init.status
+    this.code = init.code
+    this.body = init.body
+    this.requiredScope = init.requiredScope
+    this.issues = init.issues
+
+    // Keeps the constructor out of the stack, so the first frame is the caller.
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CognitiveMemoryError)
+    }
+  }
+
+  /** The key is missing, malformed, expired or revoked. */
+  isAuthError(): boolean {
+    return this.status === 401
+  }
+
+  /** The key is valid but lacks a scope. `requiredScope` says which. */
+  isScopeError(): boolean {
+    return this.status === 403
+  }
+
+  /** The request body did not match the schema. `issues` says where. */
+  isValidationError(): boolean {
+    return this.status === 400
+  }
+
+  /** Nothing exists at that id — or it belongs to another organisation. */
+  isNotFoundError(): boolean {
+    return this.status === 404
+  }
+
+  isRateLimitError(): boolean {
+    return this.status === 429
+  }
+
+  /** A dependency of ours failed, not the request. Safe to retry. */
+  isServerError(): boolean {
+    return this.status >= 500
+  }
+}