{"record":{"id":"8301edad241dfd05","repo":"JuliusBrussee/caveman","slug":"caveman-agent-context-ttlturns-must-be-a-positive","errorCode":null,"errorMessage":"caveman agent: context ttlTurns must be a positive integer","messagePattern":"caveman agent: context ttlTurns must be a positive integer","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/agent/src/primitives.ts","lineNumber":350,"sourceCode":"  readonly ttlTurns?: number;\n}\n\nexport function context(options: {\n  id: string;\n  kind: ContextKind;\n  source: string | FileSource;\n  stability: ContextStability;\n  safety?: SafetyClass;\n  priority?: ContextPriority;\n  recovery?: RecoveryKind;\n  cacheRegion?: CacheRegion;\n  privacy?: PrivacyClass;\n  opaque?: boolean;\n  ttlTurns?: number;\n}): ContextDefinition {\n  if (options.id.trim() === \"\") throw new Error(\"caveman agent: context id is required\");\n  if (options.ttlTurns !== undefined && (!Number.isSafeInteger(options.ttlTurns) || options.ttlTurns <= 0)) {\n    throw new Error(\"caveman agent: context ttlTurns must be a positive integer\");\n  }\n  const definition: ContextDefinition = {\n    kind: \"context\",\n    id: options.id,\n    segmentKind: options.kind,\n    source: options.source,\n    stability: options.stability,\n    safety: options.safety ?? \"S0\",\n    priority: options.priority ?? \"required\",\n    recovery: options.recovery ?? \"none\",\n    cacheRegion: options.cacheRegion ?? (options.stability === \"build\" ? \"frozen_prefix\" : \"live_zone\"),\n    privacy: options.privacy ?? \"local_sensitive\",\n    opaque: options.opaque ?? false,\n    ...(options.ttlTurns === undefined ? {} : { ttlTurns: options.ttlTurns }),\n  };\n  return Object.freeze(definition);\n}\n","sourceCodeStart":332,"sourceCodeEnd":368,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/3ee70a102609e550bd2e68004bf5990a9341c851/packages/agent/src/primitives.ts#L332-L368","documentation":"context() validates that ttlTurns, when provided, is a positive safe integer (Number.isSafeInteger and > 0). The library throws this error at definition time to reject context definitions with an invalid time-to-live, such as zero, negative, fractional, or non-integer values. It is a synchronous constructor-style validation so misuse fails immediately rather than silently misbehaving at runtime.","triggerScenarios":"Calling context({ id, ttlTurns }) where ttlTurns is 0, negative (e.g. -1), a float (e.g. 2.5), NaN, Infinity, or otherwise not a Number.isSafeInteger. Any other option value does not trigger this error.","commonSituations":"Computing ttlTurns from config math that yields a float or negative number; passing a string parsed value without coercion; using a default placeholder of 0 intending 'no expiry' instead of omitting ttlTurns.","solutions":["Pass a positive integer for ttlTurns (>= 1), or omit the property entirely if the context should not expire.","Validate/round the value before calling context(): Number.isSafeInteger(v) && v > 0.","If ttlTurns comes from config, coerce and check it: Math.floor(Number(raw)) and reject non-finite values."],"exampleFix":"// before\nconst ctx = context({ id: \"history\", ttlTurns: 0 });\n// after\nconst ctx = context({ id: \"history\", ttlTurns: 10 }); // or omit ttlTurns","handlingStrategy":"validation","validationCode":"function validTtlTurns(v) { return v === undefined || (Number.isSafeInteger(v) && v > 0); }\nif (!validTtlTurns(opts.ttlTurns)) throw new Error(`ttlTurns must be a positive integer, got ${opts.ttlTurns}`);","typeGuard":"function isPositiveInt(v: unknown): v is number { return typeof v === \"number\" && Number.isSafeInteger(v) && v > 0; }","tryCatchPattern":"let ctx;\ntry { ctx = context({ id: \"history\", ttlTurns }); }\ncatch (e) { if (String(e.message).includes(\"ttlTurns\")) ctx = context({ id: \"history\" }); else throw e; }","preventionTips":["Omit ttlTurns rather than passing 0 for 'no expiry'.","Coerce config values with Math.floor(Number(raw)) and validate before constructing contexts.","Centralize context creation in a helper that validates options once."],"tags":["validation","typescript","context","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"3ee70a102609e550bd2e68004bf5990a9341c851","analyzedAt":"2026-09-20T15:53:39.229Z","contentChangedAt":"2026-09-20T15:53:39.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}