import type { SourceLocation } from "../types/base.js"; import type { TypeCheckError } from "./types.js"; /** * The single source of truth for every diagnostic the type checker can emit. * * APPEND-ONLY: a shipped code is never renumbered or reused. A retired * diagnostic keeps its entry with `retired: true` so the code stays reserved. * Codes are AG#### (append-only). Category ranges live in * DIAGNOSTIC_CATEGORIES below — the single source for the docs generator * and the `agency explain --list` grouping. * * Message templates use {param} placeholders. Templates are extracted * VERBATIM from the legacy inline strings — rendered output must be * byte-identical (the migration safety gate). Conditional phrasing NEVER * goes into a param (params are structured data, not sentence fragments): * a site that built its message conditionally gets one entry per phrasing. * EXCEPTION for closed-set WORDS (not fragments): a param may hold a single * word chosen from a fixed set — e.g. {kind} = Function|Node, or * {argumentWord} = argument|arguments for pluralization — because these are * enum-like values, not free-form phrasing. * * Deliberate `loc: null` (file-level) diagnostics: NO site hardcodes null. * Every push passes the nearest AST node's loc; null occurs only dynamically, * when the AST genuinely has none — e.g. a reserved-name diagnostic on an * IMPORTED alias (no local declaration node), or a synthetic node. The * location-audit suite (diagnosticLocations.test.ts) pins the sites that * were loc-less before this registry existed. */ export declare const DIAGNOSTICS: { readonly reassignToConst: { readonly code: "AG4005"; readonly severity: "error"; readonly message: "Cannot reassign to constant '{name}'."; }; readonly regexInStructuredOutput: { readonly code: "AG6001"; readonly severity: "error"; readonly message: "'regex' cannot appear in an llm() structured-output type ({context}); LLMs can't return regex values through JSON."; }; readonly typeNotAssignableInContext: { readonly code: "AG2001"; readonly severity: "error"; readonly message: "Type '{actual}' is not assignable to type '{expected}' ({context})."; }; readonly conditionNotBoolean: { readonly code: "AG2002"; readonly severity: "error"; readonly message: "Type '{actual}' is not assignable to type 'boolean' (condition)."; }; readonly unknownProperty: { readonly code: "AG2003"; readonly severity: "error"; readonly message: "Unknown property '{key}' on type '{expected}' ({context})."; }; readonly exportRequiresStaticConst: { readonly code: "AG7001"; readonly severity: "error"; readonly message: "Only 'static const' declarations can be exported. Use 'export static const {name} = ...' instead."; }; readonly missingAnnotationStrictMode: { readonly code: "AG2004"; readonly severity: "error"; readonly message: "Variable '{name}' has no type annotation (strict mode)."; }; readonly typeNotAssignable: { readonly code: "AG2005"; readonly severity: "error"; readonly message: "Type '{actual}' is not assignable to type '{expected}'."; }; readonly forLoopIterableType: { readonly code: "AG2006"; readonly severity: "error"; readonly message: "For-loop iterable must be an array or Record, got '{actual}'."; }; readonly handlerParamValidated: { readonly code: "AG3001"; readonly severity: "error"; readonly message: "The '!' validation syntax is not allowed on handler parameters. Validate the data inside the handler body if needed."; }; readonly typeParamDefaultOrder: { readonly code: "AG1001"; readonly severity: "error"; readonly message: "Type parameter '{param}' (no default) must come before parameters that have defaults in '{alias}'."; }; readonly shadowsImportedFunction: { readonly code: "AG4001"; readonly severity: "warning"; readonly message: "'{name}' shadows an imported function."; }; readonly reservedBuiltinRedefined: { readonly code: "AG4002"; readonly severity: "error"; readonly message: "'{name}' is a reserved built-in; cannot be redefined."; }; readonly reservedBuiltinTypeRedefined: { readonly code: "AG4003"; readonly severity: "error"; readonly message: "'{name}' is a reserved built-in type; cannot be redefined."; }; readonly validatedParamsRequireResult: { readonly code: "AG2007"; readonly severity: "error"; readonly message: "{kind} '{name}' has validated parameters but its return type is not a Result type. Validated parameters can short-circuit with a failure, so the return type must be 'Result<...>'."; }; readonly docStringParamInterpolation: { readonly code: "AG6002"; readonly severity: "error"; readonly message: "Cannot interpolate parameter '{param}' in doc string — parameter values are not known when the tool description is sent to the LLM. Use a global variable instead."; }; readonly notValueParameterized: { readonly code: "AG1002"; readonly severity: "error"; readonly message: "Type '{alias}' is not a value-parameterized type but was given {count} value {argumentWord} (referenced in '{context}')."; }; readonly tooManyValueArgs: { readonly code: "AG1003"; readonly severity: "error"; readonly message: "{alias} expects at most {max} value {argumentWord}, got {count} (referenced in '{context}')."; }; readonly valueArgsRequired: { readonly code: "AG1004"; readonly severity: "error"; readonly message: "'{alias}' is a value-parameterized type and requires value arguments — write '{alias}({formals})' (referenced in '{context}')."; }; readonly tooFewValueArgs: { readonly code: "AG1005"; readonly severity: "error"; readonly message: "{alias} requires at least {min} value {argumentWord} (referenced in '{context}')."; }; readonly unknownTypeAlias: { readonly code: "AG1006"; readonly severity: "error"; readonly message: "Type alias '{alias}' is not defined (referenced in '{context}')."; }; readonly castUnrelatedTypes: { readonly code: "AG1014"; readonly severity: "error"; readonly message: "Cannot cast `{from}` to `{to}` because neither type fits the other. If this is intentional, write `{expr} as unknown as {to}`."; }; readonly castResultNotUnwrapped: { readonly code: "AG1018"; readonly severity: "error"; readonly message: "`{expr}` is a `{from}`. A cast does not unwrap it. Unwrap the Result first, with `match` or `catch`, then cast the value if you still need to."; }; readonly castNoSchema: { readonly code: "AG1015"; readonly severity: "error"; readonly message: "A checked cast validates the value at runtime, and `{type}` has no schema to validate against. Remove the `!` to cast without checking."; }; readonly castRefusedPosition: { readonly code: "AG1016"; readonly severity: "error"; readonly message: "A cast is not allowed in this position. Add parentheses: `({left} {op} {right}) as {type}` or `{left} {op} ({right} as {type})`."; }; readonly castCanPauseInOpaquePosition: { readonly code: "AG1017"; readonly severity: "error"; readonly message: "This checked cast runs validators that can pause the program, and it cannot be resumed safely in this position. Move it to its own line: `const value = {cast}`."; }; readonly castCanPauseInHandlerBody: { readonly code: "AG1020"; readonly severity: "error"; readonly message: "`{cast}` runs validators that can pause the program, and a handler body cannot pause. Do the cast before the `handle` block and use the value here."; }; readonly castCanPauseOutsideBody: { readonly code: "AG1019"; readonly severity: "error"; readonly message: "`{cast}` runs validators that can pause the program, and a module-level initializer or a parameter default cannot pause. Do the cast inside a node or a def."; }; readonly typePatternUnknownType: { readonly code: "AG1013"; readonly severity: "error"; readonly message: "`{name}` is not a type; {hint}"; }; readonly genericRequiresTypeArgs: { readonly code: "AG1007"; readonly severity: "error"; readonly message: "Generic type '{alias}' requires type arguments (referenced in '{context}')."; }; readonly builtinGenericArity: { readonly code: "AG1008"; readonly severity: "error"; readonly message: "{alias} expects {expected} type {argumentWord}, got {count} (referenced in '{context}')."; }; readonly unknownGenericType: { readonly code: "AG1009"; readonly severity: "error"; readonly message: "Unknown generic type '{alias}' (referenced in '{context}')."; }; readonly notGenericType: { readonly code: "AG1010"; readonly severity: "error"; readonly message: "Type '{alias}' is not a generic type (referenced in '{context}')."; }; readonly tooManyTypeArgs: { readonly code: "AG1011"; readonly severity: "error"; readonly message: "{alias} expects at most {max} type {argumentWord}, got {count} (referenced in '{context}')."; }; readonly tooFewTypeArgs: { readonly code: "AG1012"; readonly severity: "error"; readonly message: "{alias} requires at least {min} type {argumentWord} (referenced in '{context}')."; }; readonly bannedBuiltinInStaticInit: { readonly code: "AG7002"; readonly severity: "error"; readonly message: "{contextLabel} cannot call `{builtin}(...)` — {reason}, but static initializers run once at process startup before any per-run state exists. Move this call into a node or a function called from a node."; }; readonly interruptInStaticInit: { readonly code: "AG7003"; readonly severity: "error"; readonly message: "{contextLabel} cannot `interrupt(...)` — interrupts pause the per-run execution stack, but static initializers run once at process startup before any agent run has begun. Move this into a node body."; }; readonly interruptingCallInStaticInit: { readonly code: "AG7008"; readonly severity: "error"; readonly message: "{contextLabel} calls `{fn}`, which may interrupt [{effects}]. Interrupts pause the per-run execution stack, but static initializers run once at process startup before any agent run has begun. Move this into a node body, or answer it at the site by ending the statement with `with approve`."; }; readonly unionFieldNotOnEveryMember: { readonly code: "AG2008"; readonly severity: "error"; readonly message: "Property '{field}' is not available on every member of '{union}'; narrow the value (e.g. with a guard) before accessing it."; }; readonly resultBranchFieldAccess: { readonly code: "AG2009"; readonly severity: "error"; readonly message: "'.{field}' is only available on a {branch} Result; guard with 'if (isSuccess(r))' / 'if (isFailure(r))', use 'r catch …', or 'match (r) {{ … }}'."; }; readonly failureMessageNotString: { readonly code: "AG2013"; readonly severity: "error"; readonly message: "The first argument to failure() is the message shown to a person or a model, so it must be a string. Got '{actual}'."; }; readonly failureDataNotObject: { readonly code: "AG2014"; readonly severity: "error"; readonly message: "The second argument to failure() is its structured data, so it must be an object. Got '{actual}'."; }; readonly failureNeedsData: { readonly code: "AG2015"; readonly severity: "error"; readonly message: "This function declares '{expected}' as its failure data, so failure() needs a second argument. To allow a failure with no data, declare the return type as 'Result<{success}, {expected} | null>'."; }; readonly resultDataNotObject: { readonly code: "AG2016"; readonly severity: "error"; readonly message: "A Result's second type parameter is its failure data, and failure data must be an object. Got '{actual}' ({context}). A failure's message is always a string and is not named in the type."; }; readonly failureSplatArgument: { readonly code: "AG2017"; readonly severity: "error"; readonly message: "failure() cannot take a splat. Codegen appends the checkpoint and function name to every failure() call by position, and a splat of unknown width would displace them. Pass the message and data directly."; }; readonly dimensionMismatch: { readonly code: "AG2010"; readonly severity: "error"; readonly message: "Cannot {op} values of different dimensions ({leftDim} and {rightDim}): '{left}' and '{right}'."; }; readonly propertyDoesNotExist: { readonly code: "AG2011"; readonly severity: "error"; readonly message: "Property '{property}' does not exist on type '{type}'."; }; readonly partialRequiresNamedArgs: { readonly code: "AG6003"; readonly severity: "error"; readonly message: ".partial() requires named arguments, e.g. fn.partial(a: 5)."; }; readonly unknownPartialParameter: { readonly code: "AG6004"; readonly severity: "error"; readonly message: "Unknown parameter '{name}' in .partial() call. '{fn}' has parameters: {params}."; }; readonly partialArgNotAssignable: { readonly code: "AG6005"; readonly severity: "error"; readonly message: "Argument type '{actual}' is not assignable to parameter type '{expected}' in .partial() call to '{fn}'."; }; readonly namedArgsOnBuiltinMethod: { readonly code: "AG6006"; readonly severity: "error"; readonly message: "Named arguments are not supported on built-in method '.{method}()'."; }; readonly methodArityExact: { readonly code: "AG6007"; readonly severity: "error"; readonly message: "Method '.{method}()' expects {expected} argument(s), got {count}."; }; readonly methodArityAtLeast: { readonly code: "AG6008"; readonly severity: "error"; readonly message: "Method '.{method}()' expects at least {min} argument(s), got {count}."; }; readonly methodArityRange: { readonly code: "AG6009"; readonly severity: "error"; readonly message: "Method '.{method}()' expects {min}–{max} argument(s), got {count}."; }; readonly builtinMethodArgNotAssignable: { readonly code: "AG6010"; readonly severity: "error"; readonly message: "Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '.{method}()'."; }; readonly namedArgsOnlyAgencyFunctions: { readonly code: "AG6011"; readonly severity: "error"; readonly message: "Named arguments can only be used with Agency-defined functions, not '{fn}'."; }; readonly namedArgNotAccepted: { readonly code: "AG6012"; readonly severity: "error"; readonly message: "'{fn}' does not accept the named argument '{name}'. Allowed: {allowed}."; }; readonly duplicateNamedArg: { readonly code: "AG6013"; readonly severity: "error"; readonly message: "Duplicate named argument '{name}' in call to '{fn}'."; }; readonly namedArgTypeMismatch: { readonly code: "AG6014"; readonly severity: "error"; readonly message: "Named argument '{name}' on '{fn}' expects type '{expected}', got '{actual}'."; }; readonly blockArgNotAccepted: { readonly code: "AG6015"; readonly severity: "error"; readonly message: "'{fn}' does not accept a block argument."; }; readonly callArityExact: { readonly code: "AG6016"; readonly severity: "error"; readonly message: "Expected {expected} argument(s) for '{fn}', but got {count}."; }; readonly callArityAtLeast: { readonly code: "AG6017"; readonly severity: "error"; readonly message: "Expected at least {min} argument(s) for '{fn}', but got {count}."; }; readonly callArityRange: { readonly code: "AG6018"; readonly severity: "error"; readonly message: "Expected {min}-{max} argument(s) for '{fn}', but got {count}."; }; readonly argNotAssignable: { readonly code: "AG6019"; readonly severity: "error"; readonly message: "Argument type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'."; }; readonly splatMustBeArray: { readonly code: "AG6020"; readonly severity: "error"; readonly message: "Splat argument must be an array, got '{actual}' in call to '{fn}'."; }; readonly splatElementNotAssignable: { readonly code: "AG6021"; readonly severity: "error"; readonly message: "Splat element type '{actual}' is not assignable to parameter type '{expected}' in call to '{fn}'."; }; readonly pipeSlotNotAssignable: { readonly code: "AG6022"; readonly severity: "error"; readonly message: "Type '{actual}' is not assignable to pipe slot of type '{expected}'."; }; readonly splatAfterNamedArg: { readonly code: "AG6023"; readonly severity: "error"; readonly message: "Splat argument cannot follow a named argument in call to '{fn}'."; }; readonly positionalAfterNamedArg: { readonly code: "AG6024"; readonly severity: "error"; readonly message: "Positional argument cannot follow a named argument in call to '{fn}'."; }; readonly unknownNamedArg: { readonly code: "AG6025"; readonly severity: "error"; readonly message: "Unknown named argument '{name}' in call to '{fn}'. {valid}"; }; readonly namedArgConflictsPositional: { readonly code: "AG6026"; readonly severity: "error"; readonly message: "Named argument '{name}' conflicts with positional argument at position {position} in call to '{fn}'."; }; readonly positionalFeedsNamedVariadic: { readonly code: "AG6027"; readonly severity: "error"; readonly message: "Positional argument cannot feed variadic parameter '{param}' when it is also bound by name in call to '{fn}'."; }; readonly effectDeclaredTwice: { readonly code: "AG3002"; readonly severity: "error"; readonly message: "Effect '{effect}' is declared more than once in the same file."; }; readonly effectPayloadConflict: { readonly code: "AG3003"; readonly severity: "error"; readonly message: "Conflicting payload types for effect '{effect}'. All declarations of an effect must agree on its payload."; }; readonly namedArgsOnRaise: { readonly code: "AG3004"; readonly severity: "error"; readonly message: "Named arguments are not allowed on 'raise'/'interrupt'. Pass the data positionally."; }; readonly alwaysUnknownField: { readonly code: "AG3019"; readonly severity: "error"; readonly message: "@{tag} names '{field}', which effect '{effect}' does not carry."; }; readonly alwaysBadArgument: { readonly code: "AG3020"; readonly severity: "error"; readonly message: "@{tag} arguments must be bare field names, each named once (effect '{effect}')."; }; readonly alwaysRepeatedTag: { readonly code: "AG3021"; readonly severity: "error"; readonly message: "@{tag} appears more than once on effect '{effect}'."; }; readonly alwaysScopeConflict: { readonly code: "AG3022"; readonly severity: "error"; readonly message: "Conflicting @always scopes for effect '{effect}'. All tagged declarations of an effect must agree."; }; readonly alwaysStrayTag: { readonly code: "AG3023"; readonly severity: "error"; readonly message: "@{tag} is only valid on an effect declaration."; }; readonly capabilityUnknown: { readonly code: "AG3024"; readonly severity: "error"; readonly message: "Unknown capability '{name}' on '{callable}'. Did you mean '{suggestion}'? The capabilities are {known}."; }; readonly capabilitiesBadArgument: { readonly code: "AG3025"; readonly severity: "error"; readonly message: "@capabilities arguments must be bare capability names (on '{callable}')."; }; readonly capabilitiesRepeatedTag: { readonly code: "AG3026"; readonly severity: "error"; readonly message: "@capabilities appears more than once on '{callable}'."; }; readonly capabilitiesConflict: { readonly code: "AG3027"; readonly severity: "error"; readonly retired: true; readonly message: "RETIRED: the @capabilities tag moved from effect declarations to functions, where one declaration has one tag, so two declarations of an effect can no longer disagree."; }; readonly capabilitiesStrayTag: { readonly code: "AG3028"; readonly severity: "error"; readonly message: "@capabilities goes on a def or a node.{hint}"; }; readonly platformLacksCapability: { readonly code: "AG3029"; readonly severity: "error"; readonly message: "{kind} '{name}' needs the {capability} capability, which the {platform} platform does not have.\n{path}"; }; readonly effectDataMissing: { readonly code: "AG3005"; readonly severity: "error"; readonly message: "Effect '{effect}' expects data {payload}, but none was supplied."; }; readonly effectDataFieldMissing: { readonly code: "AG3006"; readonly severity: "error"; readonly message: "Effect '{effect}' data field '{field}' is missing."; }; readonly effectDataFieldWrongType: { readonly code: "AG3007"; readonly severity: "error"; readonly message: "Effect '{effect}' data field '{field}' has the wrong type."; }; readonly effectDataMismatch: { readonly code: "AG3008"; readonly severity: "error"; readonly message: "Effect '{effect}' data does not match the declared {payload}."; }; readonly unhandledInterrupts: { readonly code: "AG3009"; readonly severity: "warning"; readonly message: "Function '{fn}' may throw interrupts [{effects}] but is not inside a handler."; }; readonly handlerBodyRaises: { readonly code: "AG3010"; readonly severity: "error"; readonly retired: true; readonly message: "RETIRED: handler functions may raise interrupts. The dispatcher skips the executing handler for its own raises, so the recursion this diagnostic guarded against cannot happen. Remove any `// @tc-ignore AG3010` suppressions."; }; readonly interruptInCallback: { readonly code: "AG3011"; readonly severity: "error"; readonly message: "`interrupt` is not allowed inside a callback body (callback registered on '{hook}' may raise [{effects}]). Callbacks fire as side effects; their body cannot pause execution to ask the user a question. Move the `interrupt` into the calling node/function instead, or use a runtime guard if you wanted budget enforcement."; }; readonly raisesNotAnEffectSet: { readonly code: "AG3012"; readonly severity: "error"; readonly message: "'raises {ref}' is not an effect set. Declare '{ref}' with 'effectSet' (not 'type'), or use an inline set like '<...>'."; }; readonly raisesExceeded: { readonly code: "AG3013"; readonly severity: "error"; readonly message: "{kind} '{name}' raises effect '{effect}', which exceeds its declared 'raises {declared}'. Add '{effect}' to the clause."; }; readonly valueMayRaiseAnyEffect: { readonly code: "AG3014"; readonly severity: "error"; readonly message: "{who} may raise any effect (its type has no 'raises' clause), which exceeds the 'raises <{allowed}>' allowed by type '{type}'. Add a 'raises' clause to the value's type."; }; readonly valueEffectExceedsRaises: { readonly code: "AG3015"; readonly severity: "error"; readonly message: "{who} raises effect '{effect}', which exceeds the 'raises <{allowed}>' allowed by type '{type}'. Add '{effect}' to the clause, or use a target type that allows it."; }; readonly finalizeInterrupts: { readonly code: "AG3016"; readonly severity: "error"; readonly message: "'{callee}' can interrupt, and a finalize block cannot contain interrupts. A finalize runs while its scope shuts down, so there is nothing to resume."; }; readonly topLevelStatementNotAllowed: { readonly code: "AG3017"; readonly severity: "error"; readonly message: "Cannot use {kind} at the top level of a file. Top-level code runs at initialization, which cannot branch, loop, or wait — move it inside a node or a function."; }; readonly topLevelHandlerNotAllowed: { readonly code: "AG3018"; readonly severity: "error"; readonly message: "A handler cannot be registered at the top level of a file. Handlers must be inside a node or a function, where there is execution for them to guard."; }; readonly undefinedFunction: { readonly code: "AG4004"; readonly severity: "error"; readonly message: "Function '{name}' is not defined."; }; readonly importNameNotFound: { readonly code: "AG4008"; readonly severity: "error"; readonly message: "'{name}' is not defined in '{module}'."; }; readonly importModuleNotFound: { readonly code: "AG4009"; readonly severity: "error"; readonly message: "Cannot find module '{module}'."; }; readonly importNameNotExported: { readonly code: "AG4010"; readonly severity: "error"; readonly message: "'{name}' is defined in '{module}' but is not exported. Add the 'export' keyword to its definition."; }; readonly sandboxImportRefused: { readonly code: "AG4013"; readonly severity: "error"; readonly message: "{violation}"; }; readonly reservedBlockKeyword: { readonly code: "AG4006"; readonly severity: "error"; readonly message: "`{keyword}` is a reserved block keyword. Write `{keyword} {{ ... }}` or `{keyword}(args) {{ ... }}` directly — the `as` keyword is not supported on {keyword} blocks (there's nothing to bind)."; }; readonly sandboxForbiddenProperty: { readonly code: "AG4011"; readonly severity: "error"; readonly message: "'{name}' is not accessible under --agency-only. It reaches JavaScript's Function or prototype chain, which pure Agency code may not use."; }; readonly parameterRedeclared: { readonly code: "AG4012"; readonly severity: "error"; readonly message: "Cannot redeclare parameter '{name}' with '{declKind}'. Reads after the redeclare would still see the parameter. Assign to it instead, or pick a different name."; }; readonly undefinedVariable: { readonly code: "AG4007"; readonly severity: "error"; readonly message: "Variable '{name}' is not defined."; }; readonly matchNotExhaustive: { readonly code: "AG5002"; readonly severity: "error"; readonly message: "match is not exhaustive: missing {missing}."; }; readonly bareArmBinderShadowsType: { readonly code: "AG5003"; readonly severity: "warning"; readonly message: "`{name}` here binds the value; it does not test the type. Did you mean `p: {name}` or `is {name}`?"; }; readonly notAllPathsReturn: { readonly code: "AG2012"; readonly severity: "error"; readonly message: "Not all code paths return a value in '{fn}'."; }; readonly toolRequiredParamUnbound: { readonly code: "AG6028"; readonly severity: "error"; readonly message: "Tool '{tool}' has a required function-typed parameter '{param}' that is unbound. Bind it with .partial({param}: ) before passing it as a tool."; }; readonly toolRequiredParamUnboundTyped: { readonly code: "AG6029"; readonly severity: "error"; readonly message: "Tool '{tool}' has a required function-typed parameter '{param}' that is unbound (its type is {type}). Bind it with .partial({param}: ) before passing it as a tool."; }; readonly toolOptionalParamsDropped: { readonly code: "AG6030"; readonly severity: "warning"; readonly message: "Tool '{tool}' will be exposed to the LLM without optional function-typed parameter(s): {params}. The function body must be prepared to run with the declared default for each."; }; readonly saveDraftAtTopLevel: { readonly code: "AG6031"; readonly severity: "error"; readonly message: "saveDraft() cannot be called at module top level — there is no enclosing function, node, or block scope to save a draft for."; }; readonly finalizeDuplicate: { readonly code: "AG6032"; readonly severity: "error"; readonly message: "A scope can declare at most one finalize block. Combine the logic into one block."; }; readonly finalizeNotTopLevel: { readonly code: "AG6033"; readonly severity: "error"; readonly message: "A finalize block cannot go inside {construct}. Declare it at the top level of the function or block body. A finalize is always active, so nesting it in control flow has no meaning."; }; readonly finalizeSaveDraft: { readonly code: "AG6034"; readonly severity: "error"; readonly message: "saveDraft() has no effect inside a finalize block. The value the finalize returns is already the partial result. Return the value instead."; }; readonly finalizeInNode: { readonly code: "AG6035"; readonly severity: "error"; readonly message: "A finalize block cannot go in a node body. Nothing above a node consumes a partial result yet. Put the finalize in a function or a guard block instead."; }; readonly finalizeReturnShape: { readonly code: "AG6036"; readonly severity: "error"; readonly message: "This scope has a finalize block, so a return expression cannot bury a call inside a bigger expression. If the call were stopped, the expression would consume its partial result before the finalize could run. Assign the call to a local first, then return the local."; }; readonly finalizeBinderCollision: { readonly code: "AG6037"; readonly severity: "error"; readonly message: "finalize binder '{name}' collides with a variable that already exists in this scope. Pick a fresh name. The finalize body reads the scope's locals directly, so a colliding binder would silently shadow the local."; }; readonly finalizeBinderArity: { readonly code: "AG6038"; readonly severity: "error"; readonly message: "finalize yields a single value — the scope's saved draft. Use one binder: finalize as {name} {{ ... }}."; }; readonly requiredParamAfterDefault: { readonly code: "AG6039"; readonly severity: "error"; readonly message: "Parameter '{name}' on '{fn}' has no default but comes after a defaulted parameter. Put defaulted parameters last, so an omitted argument is always a trailing one."; }; readonly toolIsNotAFunction: { readonly code: "AG6040"; readonly severity: "error"; readonly message: "'{expr}' is passed as a tool, but it is a value of type '{actual}', not a function.{shadowHint}"; }; readonly staticReassignedAtTopLevel: { readonly code: "AG7004"; readonly severity: "error"; readonly message: "Cannot reassign static `{name}` at module top level — statics are immutable after initialization. Use a global (`const`/`let` without `static`) if you need a mutable value."; }; readonly staticMutatedViaMethod: { readonly code: "AG7005"; readonly severity: "error"; readonly message: "Cannot mutate static `{name}` via `.{method}(...)` at module top level — statics are deep-frozen after initialization. Use a global (`const`/`let` without `static`) if you need a mutable value."; }; readonly conflictingMarkers: { readonly code: "AG7006"; readonly severity: "error"; readonly message: "Function '{name}' cannot be both destructive and idempotent — those markers are contradictory. Pick one."; }; readonly valueArgNotStatic: { readonly code: "AG7007"; readonly severity: "error"; readonly message: "Type '{alias}' takes value argument '{name}', which is {what}. A value argument must be a literal, a 'static const', an imported name, or a value parameter of the enclosing type alias."; }; readonly unfilledHoles: { readonly code: "AG8001"; readonly severity: "error"; readonly message: "This file is a template with unfilled holes ({names}) and cannot be run directly. Load it with `loadTemplate` and fill it first."; }; readonly holeNeedsTypeAnnotation: { readonly code: "AG8002"; readonly severity: "error"; readonly message: "The hole `#{name}` is in a position that gives it no expected type. Annotate it, for example `#{name}: string`."; }; readonly spliceGeneratorNotImported: { readonly code: "AG8005"; readonly severity: "error"; readonly message: "`{name}` must be imported from another file to be used in a splice. A generator cannot be defined in the file that splices it, because it has to be compiled first."; }; readonly spliceGeneratorRaises: { readonly code: "AG8003"; readonly severity: "error"; readonly message: "Generator '{name}' may raise {effects}, so it cannot run at compile time. Compilation installs no interrupt handlers, so those operations could not complete anyway. Move the effectful work out of the generator."; }; readonly spliceGeneratorUnreadable: { readonly code: "AG8004"; readonly severity: "error"; readonly message: "Generator '{name}' cannot be checked for effects: {reason}. An empty effect list from an incomplete reading means nothing, so it is refused rather than run."; }; readonly spliceGeneratorReachesNonAgency: { readonly code: "AG8006"; readonly severity: "error"; readonly message: "The generator `{name}` reaches non-Agency code through `{importPath}`. Running a generator loads its file and every file that one imports, and loading a JavaScript module runs it, even when the generator calls nothing from it. JavaScript raises no interrupts and cannot be checked. Move `{name}` into a file that imports only `std::` modules and relative `.agency` files, and check what those files import in turn: one of them importing a JavaScript package is the same problem one step down. If the generator itself needs the JavaScript, set `allowNonAgencyGenerators` in your config, which switches this check off for every generator."; }; readonly templateNameNotDefined: { readonly code: "AG8015"; readonly severity: "error"; readonly message: "`{name}` is not defined in this template. A template can only use names it declares or imports itself, because a hole hides whatever fills it. Move the code that defines `{name}` into this template, or move the code that uses it into the fragment that defines it."; }; readonly spliceTopLevelStatement: { readonly code: "AG8014"; readonly severity: "error"; readonly message: "The generator `{name}` returned {kind}, which cannot sit at the top level of a file. Top-level code runs at initialization, which cannot branch, loop, or wait."; }; readonly spliceFragmentKindMismatch: { readonly code: "AG8007"; readonly severity: "error"; readonly message: "The generator `{name}` returned a `{actual}` fragment, but this splice is in {position} position and needs a `{expected}` fragment."; }; readonly spliceGeneratorFailed: { readonly code: "AG8008"; readonly severity: "error"; readonly message: "The generator `{name}` failed while running: {reason}"; }; readonly spliceNested: { readonly code: "AG8009"; readonly severity: "error"; readonly message: "A generator module cannot itself contain a splice. Move the inner generation into a separate module."; }; readonly spliceReferencesOuterName: { readonly code: "AG8010"; readonly severity: "error"; readonly message: "Generated code refers to `{name}`, which it neither declares nor imports. Generated code may use only names it declares itself and names it imports."; }; readonly spliceUsesReservedName: { readonly code: "AG8017"; readonly severity: "error"; readonly message: "Generated code from `{generator}` uses the name `{name}`. Names starting with two underscores are reserved for the compiler."; }; readonly spliceGeneratedExport: { readonly code: "AG8013"; readonly severity: "error"; readonly message: "The generator `{name}` produced an exported declaration (`{declared}`). Generated declarations cannot be exported yet, because other files resolve imports without running generators. Remove the `export`."; }; readonly spliceRedeclaresHostName: { readonly code: "AG8012"; readonly severity: "error"; readonly message: "The generator `{name}` declares `{declared}`, which this file already declares. Generated declarations may not replace existing ones."; }; readonly spliceArgumentNotAvailable: { readonly code: "AG8011"; readonly severity: "error"; readonly message: "The splice argument `{name}` is declared in this file, so it does not exist yet when the generator runs. Splice arguments may be literals, code literals, or imported names."; }; readonly spliceRefused: { readonly code: "AG8016"; readonly severity: "error"; readonly message: "`{file}` contains a splice, and generator execution was declined for this check, so `{name}` was not run."; }; readonly decoratorShape: { readonly code: "AG6043"; readonly severity: "error"; readonly message: "'{name}' is declared as a decorator, but {problem}"; }; readonly notADecorator: { readonly code: "AG6044"; readonly severity: "error"; readonly message: "'{name}' is not a decorator, so '@{name}' cannot go on '{target}'. Declare it as `decorator def {name}(...)`."; }; readonly decoratorMissingKeyword: { readonly code: "AG6045"; readonly severity: "error"; readonly message: "'{name}' has a decorator's parameters but is not declared as one: a parameter with a default comes before its last two, which only the call record and the block may follow. Declare it as `decorator def {name}(...)`, or put the defaulted parameter last."; }; readonly decoratorArgType: { readonly code: "AG6041"; readonly severity: "error"; readonly message: "Decorator '{name}' on '{target}' expects '{param}: {expected}', got '{actual}'."; }; readonly decoratorBodyReturn: { readonly code: "AG2018"; readonly severity: "error"; readonly message: "The body of '{target}' returns '{actual}', but decorator '{name}' takes a block returning '{expected}'."; }; readonly decoratorStackedReturn: { readonly code: "AG2019"; readonly severity: "error"; readonly message: "Decorator '{inner}' returns '{actual}', but decorator '{name}' above it on '{target}' takes a block returning '{expected}'."; }; readonly decoratorReturnMismatch: { readonly code: "AG2020"; readonly severity: "error"; readonly message: "'{target}' is declared to return '{declared}', but decorator '{name}' returns '{actual}'."; }; readonly decoratorDraftType: { readonly code: "AG2021"; readonly severity: "error"; readonly message: "The body of '{target}' saves a draft of type '{actual}', but decorator '{name}' takes a block returning '{expected}'."; }; readonly unwrapReturnTypeNotResult: { readonly code: "AG2024"; readonly severity: "error"; readonly message: "`{expr}?` returns a failure from `{name}` when the Result fails, but `{name}` is declared to return `{type}`. Declare it as `Result<{type}>`, or unwrap with `match` or `catch` instead."; }; readonly unwrapInOpaquePosition: { readonly code: "AG1021"; readonly severity: "error"; readonly message: "`{expr}?` cannot be lowered in this position. Move it to its own line: `const value = {expr}?`."; }; readonly unwrapOutsideBody: { readonly code: "AG1022"; readonly severity: "error"; readonly message: "`{expr}?` returns from a function, and a module-level initializer or a parameter default is not inside one. Use it inside a node or a def."; }; readonly unwrapInHandlerBody: { readonly code: "AG1023"; readonly severity: "error"; readonly message: "`{expr}?` cannot be used inside a handler body. Unwrap the Result before the `handle` block, or match on it here."; }; readonly unwrapInParallelArm: { readonly code: "AG1024"; readonly severity: "error"; readonly message: "`{expr}?` would return from a `parallel` arm, and an arm cannot return early. Do the unwrap inside a def the arm calls."; }; readonly unwrapInAssignmentTarget: { readonly code: "AG1025"; readonly severity: "error"; readonly message: "`{expr}?` cannot be a write target. Unwrap into a variable first, then assign to its field."; }; readonly unwrapNonResult: { readonly code: "AG2023"; readonly severity: "error"; readonly message: "`{expr}?` needs a `Result`, and `{expr}` is a `{type}`. Only a `Result` can be unwrapped with `?`."; }; readonly parameterAliasCollision: { readonly code: "AG2022"; readonly severity: "error"; readonly message: "Parameter '{param}' of '{fn}' has alias '{alias}', which is already the name or an alias of parameter '{other}'."; }; readonly namedArgumentIsAlias: { readonly code: "AG6042"; readonly severity: "error"; readonly message: "'{name}' is an alias of parameter '{param}' of '{fn}'. In Agency code, use '{param}'."; }; readonly raisesExceededViaDecorator: { readonly code: "AG3030"; readonly severity: "error"; readonly message: "{kind} '{name}' raises effect '{effect}', which exceeds its declared 'raises {declared}'. It is raised by decorator '{decorator}'. Add '{effect}' to the clause."; }; }; export type DiagnosticName = keyof typeof DIAGNOSTICS; /** * Category ranges as data (they were prose in the DIAGNOSTICS header comment). * The CLI `explain --list` grouping and the docs generator both key off this * single source. Append-only, like the codes: a new AG8xxx range means a new * entry here. `slug` is the docs filename; `title` is the human heading. */ export declare const DIAGNOSTIC_CATEGORIES: readonly [{ readonly prefix: "AG1"; readonly slug: "types-aliases"; readonly title: "Types and aliases"; }, { readonly prefix: "AG2"; readonly slug: "checking"; readonly title: "Assignability and checking"; }, { readonly prefix: "AG3"; readonly slug: "effects"; readonly title: "Interrupts, effects, and handlers"; }, { readonly prefix: "AG4"; readonly slug: "names"; readonly title: "Names, scope, and reserved words"; }, { readonly prefix: "AG5"; readonly slug: "match"; readonly title: "Match and narrowing"; }, { readonly prefix: "AG6"; readonly slug: "tools"; readonly title: "Calls, tools, and LLM usage"; }, { readonly prefix: "AG7"; readonly slug: "static-init"; readonly title: "Static init, config, and imports"; }, { readonly prefix: "AG8"; readonly slug: "templates"; readonly title: "Code templates and holes"; }]; /** The category a code belongs to, by its AG# prefix, or undefined if none. */ export declare function categoryForCode(code: string): (typeof DIAGNOSTIC_CATEGORIES)[number] | undefined; /** * The {placeholder} names of a template, as a string-literal union. * A candidate containing a brace or space is not a placeholder — it comes * from an {{escaped}} literal-brace region — and is dropped (mirrors the * runtime \w+ rule in renderMessage). */ type NonPlaceholderChar = "{" | "}" | " "; type IsPlaceholderName

= P extends `${string}${NonPlaceholderChar}${string}` ? false : true; type Placeholders = S extends `${string}{${infer P}}${infer Rest}` ? (IsPlaceholderName

extends true ? P : never) | Placeholders : never; /** * Typed params for a diagnostic: every {placeholder} in its template is a * REQUIRED key (missing one is a compile error at the call site). Extra keys * are allowed — params are the structured payload, and a site may carry * machine-readable data beyond what the message mentions (e.g. the variable * name on an assignability error whose message only shows the types). */ export type DiagnosticParams = Record, string | number> & Record; /** * Render a template. Literal braces in message text are written as {{ and }} * (unescaped after substitution, so they can never be misread as * placeholders). Throws on a missing param: typed call sites cannot hit * this, but an `as any` caller or future untyped path must fail loudly * rather than ship the string "undefined" inside a user-facing message. */ export declare function renderMessage(template: string, params: Record): string; /** * Build a TypeCheckError from the registry. `loc: null` is a DELIBERATE * file-level diagnostic (greppable), never an accident of omission. * `overrides.severity` exists for config-driven sites (strict member access, * exhaustiveness, undefined names) — the registry carries the default. */ export declare function diagnostic(name: N, params: DiagnosticParams, loc: SourceLocation | null, overrides?: { severity?: "error" | "warning"; }): TypeCheckError; export {};