The host's pure half
Assistant
Assistant.AccountBalance
MethodAccountBalance(bool IsAvailable, IReadOnlyList<Assistant.CurrencyBalance> Currencies)
Parameters
IsAvailable- Whether the provider says the balance can fund API calls.
Currencies- The balance in each currency the provider reports, in its own order.
PropertyIsAvailable
PropertyCurrencies
Assistant.AccountBalanceAmounts
MethodTryRead(string total, ref decimal amount)
Parameters
total- The provider's figure, such as
110.00. amount- The figure, when the text is one.
Returns
Assistant.AccountBalanceJson
MethodParse(string json)
Parameters
json- The response body.
Returns
Exceptions
JsonException- The body is not valid JSON.
FormatException- The body is valid JSON but not an object.
Assistant.AccountBalanceRead
PropertyBalance
null when the read produced no balance.PropertyReason
MethodOk(Assistant.AccountBalance balance)
Parameters
balance- The provider's figures.
Returns
MethodFailed(Assistant.AccountBalanceReason reason)
Parameters
reason- Why there are no figures; Ok is refused.
Returns
Exceptions
ArgumentOutOfRangeException- The reason says a balance was read.
Assistant.AccountBalanceReason
FieldOk
FieldUnsupported
404.FieldError
404.FieldTimeout
FieldUnreachable
FieldInvalid
Assistant.ApprovalMode
FieldAlwaysApprove
FieldRequireApproval
Assistant.BudgetAmount
16384 would not fit, so anything from a thousand is scaled and
shortened: 1.2k, 16k, 500k, 1M. The brief scale below ten keeps one
decimal and everything above it rounds to a whole unit, which is what caps the digits at three.
MethodFormat(long value)
value as a compact figure such as 16k.Parameters
value- The figure to format, which may not be negative.
Returns
MethodFormat(double value)
Parameters
value- The figure to format; it may be negative.
Returns
1.2k or 0.25 rather than 1.048576e+06.
Assistant.BudgetSnapshot
MethodBudgetSnapshot(long ContextTokens, int Steps, int ToolCalls, int LongestArguments, int LongestResult, int LastCompletionTokens, long Window, int MaxTokens, int LastMaxTokens, long EstimateError)
Parameters
ContextTokens- The estimated tokens of the provider request the plan would send.
Steps- The steps the current or most recent run has taken.
ToolCalls- The tool calls that run has made.
LongestArguments- The longest serialized tool-call arguments in the transcript.
LongestResult- The longest stored tool result in the transcript.
LastCompletionTokens- The most recent completion tokens the provider reported.
Window- The model's whole context window, as the provider reported it.
MaxTokens- The reply allowance the planned request would be sent with.
LastMaxTokens- The allowance the last step's request was sent with.
EstimateError- How far the last step's estimate was from the provider's count: positive when the estimate was high, negative when it was low.
PropertyContextTokens
PropertySteps
PropertyToolCalls
PropertyLongestArguments
PropertyLongestResult
PropertyLastCompletionTokens
PropertyWindow
PropertyMaxTokens
PropertyLastMaxTokens
PropertyEstimateError
PropertyEmpty
PropertyEstimateErrorMagnitude
PropertyEstimateDirection
PropertyWindowUsed
MethodMeasure(Assistant.ContextPlan plan, IReadOnlyList<Assistant.ChatMessage> stored, int steps, int toolCalls, int? lastCompletionTokens, int? lastMaxTokens, Assistant.ContextBudget budget, long estimateError)
Parameters
plan- The request plan whose figures the page shows.
stored- The complete stored transcript, which the argument and result rows still measure.
steps- The steps the current or most recent run has taken.
toolCalls- The tool calls that run has made.
lastCompletionTokens- The most recent completion tokens, or null when the provider has not reported any.
lastMaxTokens- The allowance the last step's request was sent with, or null before any step.
budget- The model's window and the reply's floor.
estimateError- How far the last step's estimate was from the provider's count.
Returns
Assistant.ChatMessage
MethodChatMessage(string Role, string Content, string ToolCallsJson, string ToolCallId, string ToolName)
Parameters
Role- The chat role, such as
system,user,assistantortool. Content- The plain-text message content.
ToolCallsJson- Complete assistant tool-call data, when present.
ToolCallId- The tool-call id for a tool result.
ToolName- The tool name for a tool result.
PropertyRole
system, user, assistant or tool.PropertyContent
PropertyToolCallsJson
PropertyToolCallId
PropertyToolName
Assistant.ChatRequest
MethodChatRequest(string Model, IReadOnlyList<Assistant.ChatMessage> Messages, IReadOnlyList<Assistant.ToolDefinition> Tools, double Temperature, int MaxTokens, string ReasoningField)
Parameters
Model- The configured model name.
Messages- The ordered transcript for this step.
Tools- The available functions.
Temperature- The configured sampling temperature.
MaxTokens- The provider's own
max_tokens, computed for this request. ReasoningField- The provider field name used for optional reasoning deltas.
PropertyModel
PropertyMessages
PropertyTools
PropertyTemperature
PropertyMaxTokens
max_tokens, computed for this request.PropertyReasoningField
Assistant.ChatRequestJson
MethodSerialize(Assistant.ChatRequest request)
Parameters
request- The request to serialize.
Returns
MethodMeasureMessage(Assistant.ChatMessage message)
Parameters
message- The message to measure.
Returns
MethodMeasureBytes(Assistant.ChatRequest request)
Parameters
request- The request to measure.
Returns
Assistant.ChatResponse
MethodChatResponse(string, string, IReadOnlyList<Assistant.ToolCall>, string, Assistant.TokenUsage)
PropertyHasContent
Assistant.ChatStreamAccumulator
MethodAdd(Assistant.ChatStreamEvent event)
Parameters
event- The provider event.
MethodComplete()
Assistant.ChatStreamEvent
Assistant.ContentDelta
MethodContentDelta(string)
Assistant.ContextBudget
assistant-one-budget-decides-what-fits).
The fractions are invariants here rather than configuration: a value that could raise one to the
whole budget would switch the guard off.
FieldBytesPerToken
FieldMinimumPromptTokens
PropertyContextWindow
PropertyMaximumOutputTokens
max_tokens the provider accepts for this model.PropertyMinimumOutputTokens
PropertyPromptBudget
PropertyToolResultChars
PropertyMessageChars
PropertyMemoryCharsPerRun
MethodCreate(long contextWindow, int maximumOutputTokens, int minimumOutputTokens)
Parameters
contextWindow- The window the provider reported, in tokens.
maximumOutputTokens- The largest reply the provider accepts, in tokens.
minimumOutputTokens- The configured floor under a reply, in tokens.
Returns
Exceptions
ArgumentOutOfRangeException- A figure is not positive, or the floor leaves less than MinimumPromptTokens of the window for the prompt.
MethodForPromptShare(long promptTokens, int maximumOutputTokens)
Parameters
promptTokens- The share of the window the prompt may spend.
maximumOutputTokens- The largest reply the provider accepts.
Returns
promptTokens.MethodMaxTokens(long estimatedPrompt)
max_tokens a request estimated at estimatedPrompt is sent with.Parameters
estimatedPrompt- The prompt's estimated size, including the estimate's margin.
Returns
PropertyEstimateMargin
Returns
Assistant.ContextPlan
MethodContextPlan(Assistant.ChatRequest Request, int MaskedToolResults, int MaskedArguments, int DroppedMessages, long OriginalTokens, long EstimatedTokens, long RequestBytes, string Error)
Parameters
Request- The request the provider is sent, with its
max_tokensresolved. MaskedToolResults- How many old tool results were replaced with placeholders.
MaskedArguments- How many long argument strings were elided.
DroppedMessages- How many transcript messages were dropped with their turns.
OriginalTokens- The request's estimated size before anything was masked or dropped.
EstimatedTokens- The estimated size of
Requestas it will be sent. RequestBytes- The exact UTF-8 bytes of
Request, for calibration. Error- Why no request can fit, when even the smallest one is too large.
PropertyRequest
max_tokens resolved.PropertyMaskedToolResults
PropertyMaskedArguments
PropertyDroppedMessages
PropertyOriginalTokens
PropertyEstimatedTokens
Request as it will be sent.PropertyRequestBytes
Request, for calibration.PropertyError
PropertyIsMasked
PropertyIsTrimmed
PropertyMaxTokens
max_tokens the planned request is sent with.Assistant.ContextPlanner
The size is the provider's own count of the last request plus an estimate of what has been appended since; see Assistant.TokenEstimator. Each message is measured once, and masking a message or dropping a turn is arithmetic over those figures. The reply's allowance follows the estimate, so what the prompt leaves and what the reply may use still add up to the window.
MethodBuild(Assistant.ChatRequest request, Assistant.ContextBudget budget, Assistant.TokenEstimator estimator)
budget.Parameters
request- The full request, with the system prompt, tool definitions and transcript.
budget- The model's window and the reply's floor.
estimator- The estimator the budget is measured with.
Returns
Assistant.ContextTrimResult
MethodContextTrimResult(Assistant.ChatRequest Request, int DroppedMessages, long EstimatedTokens, long RequestBytes, string Error)
Parameters
Request- The smallest request that was built: system prompt plus the turns kept.
DroppedMessages- How many transcript messages were omitted.
EstimatedTokens- The estimated size of
Requestas it would be sent. RequestBytes- The exact UTF-8 bytes of
Request, for calibration. Error- A safe reason no request can be built, when the newest turn cannot fit.
PropertyRequest
PropertyDroppedMessages
PropertyEstimatedTokens
Request as it would be sent.PropertyRequestBytes
Request, for calibration.PropertyError
PropertyIsTrimmed
PropertyTrimmingNote
Assistant.ContextTrimmer
MethodTrim(Assistant.ChatRequest request, long maximumTokens, Assistant.TokenEstimator estimator)
Parameters
request- The full request, whose messages are the transcript to trim.
maximumTokens- The largest estimated prompt the provider may be sent.
estimator- The estimator the budget is measured with.
Returns
Assistant.ConversationSplit
MethodConversationSplit(Assistant.ChatMessage System, IReadOnlyList<IReadOnlyList<Assistant.ChatMessage>> Turns)
Parameters
System- The system prompt when the transcript starts with one.
Turns- Whole turns, oldest first, each beginning at a user message.
PropertySystem
PropertyTurns
Assistant.ConversationTitle
FieldNewConversation
FieldMaximumLength
MethodFrom(string message)
Parameters
message- The first user message.
Returns
Assistant.ConversationTurns
MethodSplit(IReadOnlyList<Assistant.ChatMessage> messages)
system message is the system prompt; a later one is ordinary turn content.
A turn begins at each user message, or at the first message when it is not a user message,
which is the rule Assistant.ContextTrimmer has always applied.
Parameters
messages- The transcript, in provider order.
Returns
MethodFlatten(Assistant.ChatMessage system, IEnumerable<IReadOnlyList<Assistant.ChatMessage>> turns)
Parameters
system- The system prompt, when the transcript had one.
turns- The turns to keep, oldest first.
Returns
Assistant.CurrencyBalance
MethodCurrencyBalance(string Currency, string Total, string Granted, string ToppedUp)
Parameters
Currency- The currency code the provider reports, such as
CNYorUSD. Total- The total available balance, including granted and topped-up credit.
Granted- The granted balance that has not expired.
ToppedUp- The balance the owner has paid in.
PropertyCurrency
CNY or USD.PropertyTotal
PropertyGranted
PropertyToppedUp
Assistant.Finished
MethodFinished(string)
Assistant.GrepPattern
The language is the basic regular expression grep has always had, because that is what a
caller reaching for grep writes: ^, $, ., * and [...] are
metacharacters, \| is alternation, and everything else — (, ), {,
}, +, ? and a bare | included — is the literal character. That last
part is the one that matters most: a page key or a snippet of HTML is full of punctuation that an
extended regular expression would read as syntax, so a query means what it looks like until it
says otherwise.
A query with no metacharacters at all is matched as a literal substring, which is both the common case and the cheap one. Anything else is translated to the form Regex takes and compiled with RegexOptions.NonBacktracking: matching then costs at most linear time in the line, so a pattern cannot be used to burn a run's budget and no timer is needed to stop it. A construct that engine does not carry — a backreference, a lookaround — is refused rather than quietly matched as something else.
MethodTryCompile(string query, bool ignoreCase, ref Assistant.GrepPattern pattern, ref string error)
Parameters
query- The query as the caller wrote it.
ignoreCase- Whether matching ignores case.
pattern- The matcher, or null when the query was refused.
error- Why the query was refused, or null when it compiled.
MethodIsMatch(string line)
Parameters
line- One line, without its line break.
Exceptions
ArgumentNullExceptionlineisnull.
MethodTryTranslate(string, ref string, ref string)
|, (, ),
{, }, + and ? are literal here and are escaped on the way out,
\| becomes an alternation, and the class in [...] is copied as it stands because
the two languages agree inside one. ^ and $ anchor only at the ends of the query,
which is where a basic expression anchors them: in the middle they are the character, so a
search for $5 or x^2 means what it looks like.
MethodCopyClass(string, ref int, StringBuilder)
Assistant.MaskOutcome
MethodMaskOutcome(Assistant.ChatMessage Message, int MaskedResults, int MaskedArguments)
Parameters
Message- The message to send: the original when nothing was elided.
MaskedResults- 1 when a tool result was replaced with a placeholder.
MaskedArguments- How many long argument strings were elided.
PropertyMessage
PropertyMaskedResults
PropertyMaskedArguments
PropertyChanged
Assistant.MemoryCandidate
MethodMemoryCandidate(long Id, Assistant.MemoryKind Kind, string Content, int Version, DateTimeOffset Written, DateTimeOffset? LastUsed, int RecallCount, bool Pinned, long? SourceConversationId)
Parameters
Id- The memory's id, which is what a tool call names and the block labels.
Kind- What kind of note it is.
Content- The note's text, already normalised.
Version- The version a later update or edit has to carry to be accepted.
Written- When this version was written.
LastUsed- When it was last recalled, or null when it never was.
RecallCount- How many runs have recalled it.
Pinned- Whether the owner pinned it, which only the owner may change.
SourceConversationId- The conversation this version came from, or null once that conversation has been deleted. Only the owner's page uses it: the model cannot open a conversation and has no use for its id.
PropertyId
PropertyKind
PropertyContent
PropertyVersion
PropertyWritten
PropertyLastUsed
PropertyRecallCount
PropertyPinned
PropertySourceConversationId
Assistant.MemoryContent
MethodNormalise(string content, int maximumChars)
Parameters
content- The model-supplied text.
maximumChars- The configured length cap, in characters.
Returns
MethodSameNote(string left, string right)
Parameters
left- One normalised memory.
right- Another normalised memory.
Returns
Assistant.MemoryContentResult
MethodMemoryContentResult(string Content, string Error)
Parameters
Content- The normalised text, or the empty string when the content was refused.
Error- A sentence the model can act on, or null when the content is usable.
PropertyContent
PropertyError
PropertyIsSuccess
MethodRefused(string error)
Parameters
error- Why the content was refused.
Returns
Assistant.MemoryGroup
MethodMemoryGroup(Assistant.MemoryKind Kind, IReadOnlyList<Assistant.MemoryCandidate> Memories)
Parameters
Kind- The kind the heading names.
Memories- Its memories, pinned first and newest change first after that.
PropertyKind
PropertyMemories
Assistant.MemoryKind
FieldPreference
FieldFact
FieldFeedback
FieldReference
Assistant.MemoryKinds
PropertyAll
MethodName(Assistant.MemoryKind kind)
Parameters
kind- The kind to name.
Returns
MethodTryParse(string text, ref Assistant.MemoryKind kind)
Parameters
text- The name, matched case-insensitively.
kind- The kind, when the name is one of the four.
Returns
Assistant.MemoryListing
MethodGroup(IReadOnlyList<Assistant.MemoryCandidate> memories)
Parameters
memories- The owner's memories, in any order.
Returns
Assistant.MemoryQuery
*. Unquoted user text would be FTS5 syntax,
and a stray OR, NEAR( or unbalanced quote would be a syntax error rather than a
search. Quoting also means a term that happens to be an FTS5 operator is a word like any other.
FieldMinimumTermLength
MethodTerms(string message, int maximum)
Parameters
message- The newest user message.
maximum- The most terms to keep, matching the configured query-term cap.
Returns
Assistant.MemoryRecall
FieldTagAllowance
MethodSelect(IReadOnlyList<Assistant.MemoryCandidate> pinned, IReadOnlyList<Assistant.MemoryCandidate> used, IReadOnlyList<Assistant.MemoryCandidate> query, int maximumChars)
Parameters
pinned- The owner's pinned memories, newest change first.
used- The memories this conversation has already used, most recently used first.
query- The query's best matches, best first.
maximumChars- The most characters the block may cost, a fraction of the context budget.
Returns
MethodBuild(Assistant.MemorySelection selection)
Parameters
selection- The memories one run was given.
Returns
Assistant.MemorySecrets
FieldPrivateKey
FieldAssignment
FieldProviderKey
FieldEncodedValue
MethodLooksLikeSecret(string content)
Parameters
content- The normalised text of a memory.
Returns
Assistant.MemorySelection
MethodMemorySelection(IReadOnlyList<Assistant.MemoryCandidate> Memories, int Characters, bool Truncated)
Parameters
Memories- The chosen memories, in the order the block lists them.
Characters- What the block costs: each memory's content and its tag allowance.
Truncated- Whether a candidate that fitted the count did not fit the characters.
PropertyMemories
PropertyCharacters
PropertyTruncated
PropertyIsEmpty
Assistant.PageLineEdit
MethodPageLineEdit(int StartLine, int EndLine, string Replacement, string ExpectFirst, string ExpectLast)
Parameters
StartLine- The first 1-based physical line to replace.
EndLine- The last 1-based physical line to replace, inclusive.
Replacement- The replacement source, which may contain line breaks.
ExpectFirst- The exact text the first line must still hold, or null to accept whatever is there. A mismatch refuses the edit, so a line number that is off by one cannot silently replace the wrong line.
ExpectLast- The exact text the last line must still hold, or null to accept whatever is there.
PropertyStartLine
PropertyEndLine
PropertyReplacement
PropertyExpectFirst
PropertyExpectLast
Assistant.PageRangeEditResult
MethodPageRangeEditResult(string Content, string Error)
Parameters
Content- The new source, or null when validation failed.
Error- A safe validation error, or null when replacement succeeded.
PropertyContent
PropertyError
PropertyIsSuccess
Assistant.PageRangeEditor
MethodReplace(string source, int startLine, int endLine, string replacement, int maximumChars)
Parameters
source- The complete current page source.
startLine- The first 1-based physical template-source line to replace.
endLine- The last 1-based physical template-source line to replace, inclusive.
replacement- The replacement source, which may contain line breaks.
maximumChars- The maximum resulting source length.
MethodReplace(string source, int startLine, int endLine, string replacement, int maximumChars, string expectFirst, string expectLast)
Parameters
source- The complete current page source.
startLine- The first 1-based physical template-source line to replace.
endLine- The last 1-based physical template-source line to replace, inclusive.
replacement- The replacement source, which may contain line breaks.
maximumChars- The maximum resulting source length.
expectFirst- The exact text of
startLine, or null to accept whatever is there. expectLast- The exact text of
endLine, or null to accept whatever is there.
MethodReplaceAll(string source, IReadOnlyList<Assistant.PageLineEdit> edits, int maximumChars)
Parameters
source- The complete current page source.
edits- The replacements, whose line numbers all refer to
source. maximumChars- The maximum resulting source length.
Returns
Assistant.PageWrites
{"ok":…,"data":{"path":…},"error":…}), and a result
too large to store is replaced by a failure envelope, so a success envelope always parses.
MethodWritten(bool changesPages, string resultJson)
Parameters
changesPages- Whether the tool changes a stored page, as the tool itself says.
resultJson- The stored result of that call.
Returns
null when the call was not
a page write, did not succeed, or named a key no request can address.Assistant.PromptSizes
PropertySizes
PropertyTotal
MethodMeasure(Assistant.ChatRequest request)
Parameters
request- The request to measure.
Returns
MethodBody(long messageBytes, int count)
Parameters
messageBytes- The summed sizes of the messages kept.
count- How many messages are kept.
Returns
MethodSizeOf(Assistant.ChatMessage message)
Parameters
message- A message from the measured request.
Returns
MethodOf(IReadOnlyList<Assistant.ChatMessage> messages)
Parameters
messages- The messages to carry.
Returns
Assistant.ReasoningDelta
MethodReasoningDelta(string)
Assistant.RunUsage
MethodRunUsage(int PromptTokens, int CompletionTokens, int CachedTokens, int ReasoningTokens, int LastCompletionTokens)
Parameters
PromptTokens- Every step's prompt tokens added together.
CompletionTokens- Every step's completion tokens added together.
CachedTokens- Every step's cache-hit prompt tokens added together.
ReasoningTokens- Every step's reasoning completion tokens added together.
LastCompletionTokens- The most recent step's completion tokens, which the completion budget counts.
PropertyPromptTokens
PropertyCompletionTokens
PropertyCachedTokens
PropertyReasoningTokens
PropertyLastCompletionTokens
PropertyEmpty
PropertyTotalTokens
MethodAdd(Assistant.TokenUsage usage)
Parameters
usage- The step's report, or null when the provider did not send one.
Returns
Assistant.TokenCalibration
MethodTokenCalibration(long RequestBytes, int PromptTokens)
Parameters
RequestBytes- The exact UTF-8 bytes of the request that report describes: the anchor.
PromptTokens- The prompt tokens the provider reported for that request.
PropertyRequestBytes
PropertyPromptTokens
PropertyIsUsable
PropertyBytesPerToken
Assistant.TokenEstimator
assistant-tokens-anchor-on-the-last-report). Masking and dropping change the request by
known byte amounts, so they move the anchor by that amount and nothing else. Before the first
report there is no anchor, and the whole request is estimated with the densest ratio the tokenizer
spike measured (JSON at about 1.6 bytes per token).
FieldDefaultBytesPerToken
FieldDeltaMargin
FieldMinimumBytesPerToken
FieldMaximumBytesPerToken
MethodTokenEstimator(double bytesPerToken, double margin)
Parameters
bytesPerToken- The bytes one token is expected to cost.
margin- How much to raise the estimate; one means no margin.
PropertyBytesPerToken
PropertyMargin
PropertyAnchor
MethodFor(Assistant.TokenCalibration calibration)
Parameters
calibration- The last request's bytes and prompt tokens, or null when there is none.
Returns
MethodEstimate(Assistant.ChatRequest request)
Parameters
request- The request whose serialized body is measured.
Returns
MethodEstimate(long requestBytes)
Parameters
requestBytes- The UTF-8 bytes of the serialized body.
Returns
Assistant.TokenUsage
MethodTokenUsage(int? PromptTokens, int? CompletionTokens, int? CachedTokens, int? ReasoningTokens)
Parameters
PromptTokens- The input tokens the provider reported.
CompletionTokens- The output tokens the provider reported.
CachedTokens- The prompt tokens the provider served from its cache, when it says.
ReasoningTokens- The completion tokens spent on reasoning, when the provider says.
PropertyPromptTokens
PropertyCompletionTokens
PropertyCachedTokens
PropertyReasoningTokens
Assistant.ToolArgumentSchema
MethodToolArgumentSchema(string Name, Assistant.ToolArgumentType Type, bool Required)
Parameters
Name- The exact property name.
Type- The JSON value type.
Required- Whether the property must be present.
PropertyName
PropertyType
PropertyRequired
Assistant.ToolArgumentType
FieldString
FieldInteger
FieldBoolean
FieldArray
Assistant.ToolArguments
MethodParse(string json, IReadOnlyList<Assistant.ToolArgumentSchema> schema, int maximumChars)
Parameters
json- The provider-supplied argument JSON.
schema- The complete set of accepted argument names and types.
maximumChars- The maximum serialized argument length.
Assistant.ToolArgumentsResult
MethodToolArgumentsResult(IReadOnlyDictionary<string, JsonElement> Values, string Error)
Parameters
Values- Cloned JSON values for the declared properties.
Error- A safe validation failure, or null when valid.
PropertyValues
PropertyError
PropertyIsSuccess
Assistant.ToolCall
MethodToolCall(int, string, string, string)
Assistant.ToolCallDelta
MethodToolCallDelta(int, string, string, string)
Assistant.ToolDefinition
MethodToolDefinition(string Name, string Description, bool NeedsApproval, string ParametersJson)
Parameters
Name- The stable tool name.
Description- The provider-visible description.
NeedsApproval- Whether RequireApproval mode pauses before execution.
ParametersJson- The JSON Schema object for the tool arguments.
PropertyName
PropertyDescription
PropertyNeedsApproval
PropertyParametersJson
Assistant.ToolResultMasker
assistant-old-tool-results-are-masked).
FieldMaximumArgumentLength
FieldMaximumArgumentDepth
MethodMaskableMessages(IReadOnlyList<Assistant.ChatMessage> messages)
Parameters
messages- The request's messages, in provider order.
Returns
MethodMask(Assistant.ChatMessage message)
Parameters
message- The message to offer to the masker.
Returns
Assistant.UsageEvent
MethodUsageEvent(Assistant.TokenUsage)
Charting
Charting.ChartAxis
MethodChartAxis(string Title, IReadOnlyList<Charting.ChartTick> Ticks, double Divisor)
Parameters
Title- What the axis measures, for the chart's description.
Ticks- The ticks, in any order; the chart sorts them by position.
Divisor- What the samples are divided by to reach the ticks' units — 1000 for an axis of kilobytes. The values a chart is given stay in the unit they were recorded in, so an axis that rescales its labels has to say how far it rescaled them rather than leave the plot in a different unit from its labels.
PropertyTitle
PropertyTicks
PropertyDivisor
MethodScale(double? value)
Parameters
value- The sample, in the unit it was recorded in.
Returns
Charting.ChartChrome
FieldTitleHeight
FieldLegendRowHeight
FieldFontSize
FieldTitleFontSize
FieldSeriesFontSize
FieldLeftMargin
FieldRightMargin
FieldBottomMargin
MethodBegin(StringBuilder svg, Charting.ChartSize size, string cssClass, Charting.ChartFrame frame, string description)
Parameters
svg- The drawing being written.
size- The full drawing area.
cssClass- The drawing's class:
chart,heatmaporstacked. frame- The chart's own words.
description- The longer description an assistive technology reads.
MethodLayoutLegend(Charting.ChartSize size, double top, IReadOnlyList<string> labels, ref double plotTop)
Parameters
size- The full drawing area.
top- The band's foot, from Begin.
labels- The series labels, in series order.
plotTop- Where the plot starts once the legend has wrapped.
MethodBeginPlot(StringBuilder svg, Charting.ChartSize size, string cssClass, Charting.ChartFrame frame, string description, IReadOnlyList<string> labels, ref IReadOnlyList<Charting.LegendEntry> legend)
Parameters
svg- The drawing being written.
size- The full drawing area.
cssClass- The drawing's class:
chart,heatmaporstacked. frame- The chart's own words.
description- The longer description an assistive technology reads.
labels- The series labels, in series order.
legend- Where each legend entry sits.
Returns
MethodPlot(Charting.ChartSize size, double top)
Parameters
size- The full drawing area.
top- Where the band ends and the plot may start.
Returns
Exceptions
ArgumentOutOfRangeException- The size leaves no room to plot in.
MethodWriteLegendItem(StringBuilder svg, Charting.LegendEntry entry, string label)
Parameters
svg- The drawing being written.
entry- Where the entry goes.
label- The series label.
MethodWriteAxisTitle(StringBuilder svg, string title, Charting.ChartPlot plot)
Parameters
svg- The drawing being written.
title- What the axis measures.
plot- The plot it names.
MethodWriteValueGrid(StringBuilder svg, IEnumerable<Charting.ChartTick> ticks, Charting.ChartPlot plot, Func<double, double> at)
Parameters
svg- The drawing being written.
ticks- The value ticks, in any order.
plot- The plot they cross.
at- Where a tick's value sits vertically.
MethodWriteTimeGrid(StringBuilder svg, Charting.ChartTimeAxis axis, Charting.ChartPlot plot, Charting.ChartSize size)
Parameters
svg- The drawing being written.
axis- The time axis, whose ticks the grid is drawn at.
plot- The plot they cross.
size- The full drawing area, whose floor the labels sit above.
MethodWriteTimeLabels(StringBuilder svg, Charting.ChartTimeAxis axis, Charting.ChartPlot plot, Charting.ChartSize size)
Parameters
svg- The drawing being written.
axis- The time axis, whose ticks the labels name.
plot- The plot the labels sit under.
size- The full drawing area, whose floor the labels sit above.
MethodBeginSeries(StringBuilder svg, Charting.ChartFrame frame, int index, string label, Charting.LegendEntry legend)
Parameters
svg- The drawing being written.
frame- The chart's own words, which prefix the fragment id.
index- The series position, which decides the colour and the dash.
label- The series label.
legend- Where the series' legend entry sits.
MethodEndSeries(StringBuilder svg)
Parameters
svg- The drawing being written.
MethodEmpty(StringBuilder svg, Charting.ChartPlot plot, string message)
Parameters
svg- The drawing being written.
plot- The plot that has no data.
message- What to say.
MethodBorder(StringBuilder svg, Charting.ChartPlot plot)
Parameters
svg- The drawing being written.
plot- The plot to frame.
MethodDescribe(Charting.ChartTimeAxis x, Charting.ChartAxis y)
desc.Parameters
x- The time axis.
y- The value axis.
MethodInstant(DateTimeOffset at, TimeZoneInfo zone, TimeSpan span)
Parameters
at- The instant.
zone- The zone to write it in.
span- The window's duration, which decides whether the date is worth naming.
Charting.ChartClip
MethodLine(IReadOnlyList<ValueTuple<double, double>> line, Charting.ChartPlot plot)
Parameters
line- The line's points, in drawing order.
plot- The plot to cut it to.
Returns
MethodStack(IReadOnlyList<ValueTuple<double, double, double>> columns, Charting.ChartPlot plot)
Parameters
columns- Each column's position and the two values that bound the band.
plot- The plot to cut them to.
Returns
Charting.ChartFrame
MethodChartFrame(string Id, string Title, string YTitle, string EmptyText, TimeZoneInfo Zone, string TitleHref)
Parameters
Id- The fragment prefix for the series anchors; it is unique within one document.
Title- The drawing's title, for its accessible name and its title band.
YTitle- What the value axis measures.
EmptyText- What to draw when there is nothing to draw.
Zone- The zone the time labels and the hover text are written in.
TitleHref- Where the title links to, or null for a drawing that is already the page the title would open. The page passes its chart URL; the chart endpoint passes nothing, so a hotlinked chart never links to itself.
PropertyId
PropertyTitle
PropertyYTitle
PropertyEmptyText
PropertyZone
PropertyTitleHref
PropertyDescription
MethodValidate()
Exceptions
ArgumentException- The id or the title is blank.
Charting.ChartPlot
MethodChartPlot(double Left, double Top, double Width, double Height)
Parameters
Left- The value axis.
Top- The plot's upper edge.
Width- How wide the plot is.
Height- How tall the plot is.
PropertyLeft
PropertyTop
PropertyWidth
PropertyHeight
PropertyRight
PropertyBottom
MethodTime(Charting.ChartTimeAxis axis, double seconds)
Parameters
axis- The time axis, which owns the window.
seconds- The offset into the window, in seconds after its start.
MethodValue(double value, double min, double max)
Parameters
value- The value, in the axis' own unit.
min- The value at the plot's foot.
max- The value at its head.
Charting.ChartPoint
MethodChartPoint(DateTimeOffset At, double? Value)
Parameters
At- When the sample was taken.
Value- The value, or null for a gap — Prometheus reports gaps as
NaN.
PropertyAt
PropertyValue
NaN.Charting.ChartSamples
MethodWiden(double min, double max)
Parameters
min- The lowest value.
max- The highest value, equal to
min.
Charting.ChartSeries
MethodChartSeries(string Label, IReadOnlyList<Charting.ChartPoint> Points)
Parameters
Label- The legend text; it is escaped where it is drawn.
Points- The samples, ordered by instant.
PropertyLabel
PropertyPoints
Charting.ChartSize
MethodChartSize(double Width, double Height)
Parameters
Width- The full width, including the space the labels need.
Height- The full height, including the space the labels need.
PropertyWidth
PropertyHeight
PropertyPlotWidth
Charting.ChartTick
MethodChartTick(double Position, string Label)
Parameters
Position- The value the tick marks: seconds after the window's start on a time axis, the sample value itself on a value axis.
Label- The text to draw; it is escaped where it is drawn.
PropertyPosition
PropertyLabel
Charting.ChartTimeAxis
MethodChartTimeAxis(string Title, DateTimeOffset From, DateTimeOffset To, IReadOnlyList<Charting.ChartTick> Ticks)
Parameters
Title- What the axis measures, for the chart's description.
From- The instant at the axis' left edge.
To- The instant at its right edge.
Ticks- The ticks, positioned in seconds after
From.
PropertyTitle
PropertyFrom
PropertyTo
PropertyTicks
From.MethodOffset(DateTimeOffset at)
Parameters
at- The instant to place.
PropertySpan
PropertyDuration
Charting.Heatmap
Prometheus exposes an explicit-bucket histogram as cumulative counters, one series per le
boundary. The count in a bucket is the difference between its boundary and the one below it, and
drawing the cumulative values would show every row as a superset of the row above.
Sixteen heatmaps on one page have to fit in a budget, so a row is drawn as runs: neighbouring cells
of the same shade become one rect with one hover title, and an answer with more columns than
the cap allows is folded into blocks before anything is drawn. Each row is an anchor, so hovering or
clicking a row dims the others and clicking pins it, the same way a line chart's series behave.
FieldMaxColumns
MethodFromCumulative(IReadOnlyList<Charting.HeatmapRow> cumulative)
Parameters
cumulative- The
leseries, in any order.
Returns
+Inf last, each holding the count that fell in that bucket.
A negative difference is clamped to zero, because a counter reset is not a negative count.
MethodRender(IReadOnlyList<Charting.HeatmapRow> rows, Charting.ChartTimeAxis x, Charting.ChartSize size, Charting.ChartFrame frame, string valueUnit)
Parameters
rows- The per-bucket rows, already differenced.
x- The time axis: the window the plot covers and its ticks, positioned in seconds after the window's start.
size- The full drawing area, labels included.
frame- The drawing's title, bucket unit and words for no data.
valueUnit- The unit of the cell values, for the legend and the hover text.
Returns
<svg> element.Exceptions
ArgumentNullException- A required argument is null.
ArgumentOutOfRangeException- The size leaves no room to draw in.
MethodFold(IReadOnlyList<Charting.HeatmapRow> rows, int cap)
cap columns, summing each block.Parameters
rows- The differenced rows.
cap- The most columns to draw.
Charting.HeatmapRow
MethodHeatmapRow(string Label, IReadOnlyList<Charting.ChartPoint> Points)
Parameters
Label- The bucket boundary, for example
0.05or+Inf. Points- The samples; a null value is a gap.
PropertyLabel
0.05 or +Inf.PropertyPoints
Charting.LegendEntry
MethodLegendEntry(int Index, double X, double Y)
Parameters
Index- The series position, which decides the colour and the dash.
X- The left edge of the key sample.
Y- The top of the entry.
PropertyIndex
PropertyX
PropertyY
Charting.LineChart
Pure and deterministic: the same input produces the same string, so the tests assert on markup. Every visual value is a presentation attribute, so a drawing served on its own is legible without a stylesheet; the classes are hooks for the page's hover and pinned states.
A series is identified four ways, in the order a reader meets them: its colour, its dash pattern, a label at the end of its line, and a legend inside the drawing. Each series' legend entry sits in the same anchor as the line itself, so hovering or clicking either one highlights the same series.
MethodRender(IReadOnlyList<Charting.ChartSeries> series, Charting.ChartTimeAxis x, Charting.ChartAxis y, Charting.ChartSize size, Charting.ChartFrame frame)
Parameters
series- The lines to draw; a null value is a gap rather than a zero.
x- The time axis: the window the plot covers and its ticks, positioned in seconds after the window's start.
y- The value axis; tick positions are the values themselves, and its divisor rescales the samples into the unit the ticks are labelled in.
size- The full drawing area, labels included.
frame- The drawing's title, axis title and words for no data.
Returns
<svg> element, with every label escaped.Exceptions
ArgumentNullException- A required argument is null.
ArgumentOutOfRangeException- The size leaves no room to plot in.
Charting.NiceTicks
Both selectors use a fixed table of steps rather than arithmetic on the span, so a time label
reads 15:30 rather than 15:27 and a value label reads 0.5 rather than
0.4737.
Time positions are seconds after from, which is how the charts place their samples. The zone
only decides the label text: the ticks themselves are instants.
MethodForTime(DateTimeOffset from, DateTimeOffset to, TimeZoneInfo zone, double availableWidth)
Parameters
from- The left edge of the chart.
to- The right edge of the chart.
zone- The zone the labels are written in.
availableWidth-
The room the labels have, in drawing units. A finite width coarsens the ticks until the labels
fit; an infinite one, or the default, asks for at most
NiceTicks.TargetTickslabels.
Returns
from. A span with no width yields a
single tick rather than none.
MethodForValue(double min, double max)
Parameters
min- The lowest value on the chart.
max- The highest value on the chart.
Returns
0..1.
Charting.StackedAreaChart
A stacked area is for the panels where the labels are parts of one total: the sum is the top edge, and a reader can see both the whole and one part without switching charts. It is not a way to draw any line chart — a line whose labels do not partition the total belongs in Charting.LineChart.
A missing sample is zero, not a gap: for the counters this chart is for, a step with no series means no events in that step, and a hole in the middle of a stack would break every band above it. A negative value is refused rather than drawn as a shape a counter cannot have.
MethodRender(IReadOnlyList<Charting.ChartSeries> series, Charting.ChartTimeAxis x, Charting.ChartAxis y, Charting.ChartSize size, Charting.ChartFrame frame)
Parameters
series- The parts; they are stacked in label order, not in the order given.
x- The time axis: the window the plot covers and its ticks, positioned in seconds after the window's start.
y- The value axis; its title is drawn and its ticks are ignored, because the range is the sum of the bands and is chosen here.
size- The full drawing area, labels included.
frame- The drawing's title, axis title and words for no data.
Returns
<svg> element, with every label escaped.Exceptions
ArgumentNullException- A required argument is null.
ArgumentOutOfRangeException- The size leaves no room to plot in.
ArgumentException- A value is negative, which a stack cannot draw.
Charting.SvgText
Everything a drawing needs in order to be legible is written as a presentation attribute — the stroke, the dash, the fill, the type size — so the same SVG reads correctly with no stylesheet at all. That is what lets a chart be served on its own. The class names remain as hooks for the two things that are page-only: the hover dim and the pinned state.
The palette is Okabe–Ito's colourblind-safe set with the yellow left out, because yellow on paper is a highlight rather than a line. Four dash patterns cycle with the seven colours, so two series can share a colour and still be told apart without relying on the colour at all.
FieldSeriesColours
FieldHeatLevels
FieldFontFamily
FieldTypeScale
FieldCharacterWidth
MethodEscape(string value)
Parameters
value- The text, which may be null.
MethodNumber(double value)
Parameters
value- The number to write.
MethodSeriesColour(int index)
Parameters
index- The series position, counted from zero.
MethodSeriesStroke(int index)
Parameters
index- The series position, counted from zero.
MethodSeriesDash(int index)
Parameters
index- The series position, counted from zero.
MethodHeatFill(int level)
Parameters
level- The level, clamped to the palette's range.
MethodEstimateWidth(string text)
Parameters
text- The label.
Compilation
Compilation.ApiReference
MethodApiReference(string Namespace, string Type, string Member, Compilation.TemplatePosition? Position)
Parameters
Namespace- The namespace the API lives in, for example
System.IO. Type- The type name without its namespace, for example
File. Member- The member used, or string.Empty for a plain type reference.
Position- Where the reference appears in template space, or null when it is generated code.
PropertyNamespace
System.IO.PropertyType
File.PropertyMember
PropertyPosition
Compilation.GeneratedSource
MethodGeneratedSource(string text)
Parameters
text- The C# the template generator produced.
Exceptions
ArgumentException- The text is empty.
PropertyText
Compilation.PageApiPolicy
Default deny: a type is usable only because it appears below, so a new capability in the base class library is not granted to page code by accident. The list is data rather than a filter chain so a rejection is one readable line away from being fixed, and the diagnostic names the exact API to add.
A type is admitted when its only effect is to compute over a value the page already holds or to
shape a value the page already returns. It is refused when it adds a way to reach a resource — a
file, the network, a process, the environment, an assembly, reflection, or process-wide state.
A type that bundles a way to reach with a useful helper is admitted with the reaching members
denied by name in s_deniedApis, which is what Task does. The list grows by that
test, not by whichever feature needed an entry last.
Deliberately absent, and why: System.Object (its GetType would hand a page
reflection), System.Type, System.IO, System.Net, System.Diagnostics,
System.Reflection, System.Linq.Expressions, System.Threading beyond the
cancellation token, System.Runtime.InteropServices, System.Runtime.Loader,
System.Runtime.CompilerServices, System.Text.RegularExpressions, and anything in
Microsoft.* or our own shell assemblies. System.Net stays out on purpose:
IHttpFetch is the page's only egress.
System.Threading.Tasks is admitted as a type rather than as a namespace: exactly
Task is allowed, so a page can write and await a task, and
TaskCompletionSource, TaskScheduler, Parallel and ValueTask stay
denied without being named. Ten of Task's own members are denied by name in
s_deniedApis, because each starts work the render deadline cannot stop or turns an
await back into a blocked thread.
Cryptography is admitted as named types, not as a namespace: System.Text.Encoding to turn
text into bytes, the SHA-2 hashes and the matching HMACs to hash and sign, a random source for a
nonce, and a constant-time comparison for a signature a page checks. Nothing that manages keys,
reads a certificate or uses an asymmetric primitive is admitted: a private key has no business in
a stored page, and a credential belongs in Pages:Fetch:Credentials.
MethodCheck(IEnumerable<Compilation.ApiReference> used)
Parameters
used- The APIs the page referenced, in the order they appear.
Returns
Compilation.PageDiagnostic
MethodPageDiagnostic(Compilation.PageDiagnosticSeverity Severity, Compilation.TemplatePosition? Position, string Message)
Parameters
Severity- Whether the page can still run.
Position- Where in the template, or
nullwhen the position is not known. Message- The diagnostic code and text, without severity or position.
PropertySeverity
PropertyPosition
null when the position is not known.PropertyMessage
PropertySource
null for the page being
compiled. A library compiled into a page contributes its diagnostics under its own key.
MethodSortedForDisplay(IEnumerable<Compilation.PageDiagnostic> diagnostics)
Parameters
diagnostics- The diagnostics to order.
Returns
MethodToString()
Compilation.PageDiagnosticSeverity
FieldWarning
FieldError
Compilation.ScriptSkeletonResult
MethodScriptSkeletonResult(string Source, IReadOnlyList<Compilation.PageDiagnostic> Diagnostics)
Parameters
Source- The template's text with every template construct blanked, or an empty string when the template could not be tokenized.
Diagnostics- The tokenizer's errors, already positioned in template space; empty when a skeleton was produced.
PropertySource
PropertyDiagnostics
PropertyIsSuccess
Compilation.TemplateComments
A page with no code is served from its stored source rather than compiled, and a comment is neither code nor text, so the body a browser receives is the source less its comments. That is the one place a template's constructs are taken out of the bytes rather than blanked: Compilation.TemplateScriptSkeleton keeps a construct's width so a parser's positions hold, while this returns what the visitor should have got.
A comment removes itself entirely, as a code block that writes nothing does, rather than leaving whitespace in its place.
MethodRemove(string template)
Parameters
template- The template as its author wrote it.
Returns
<%# … %> removed and everything else unchanged, or
the template as it was when it holds no comment or cannot be tokenized — a template the
tokenizer refused is stored with its error and never served, so dropping the rest of it would
answer with less than the author wrote.
Compilation.TemplateFingerprint
A stored compiled image is only reused while its fingerprint still matches the source it was built from, so an edit that bypasses the editor cannot be answered with stale code.
The value is an opaque token compared with a freshly computed one and never parsed, so it carries no algorithm marker. Changing the algorithm changes this assembly, which changes the runtime id stored beside every image; each image stops matching and is compiled again. Hexadecimal is chosen over base64 for a single canonical form, for use in a URL or an entity tag later without escaping, and for readability in the database. The 21 bytes per page that base64 would save do not matter at this size.
MethodOf(string template)
Parameters
template- The template source.
Returns
Compilation.TemplateGenerationResult
MethodTemplateGenerationResult(Compilation.GeneratedSource Source, IReadOnlyList<Compilation.PageDiagnostic> Errors)
Parameters
Source- The generated source, or
nullwhen the template did not parse. Errors-
The problems that stopped generation, already positioned in template space; empty when
Sourcewas generated.
PropertySource
null when the template did not parse.PropertyErrors
Source was generated.
PropertyKind
A template with no code is Text, one with only declaration blocks is a Library, and anything else renders as a Page. The verdict is required rather than defaulted, so a caller cannot forget it and leave a page looking like an asset.
A declaration-only source is a library here even when it is really a worker: telling them apart needs the compiled types, so the compiler refines that verdict when the source is compiled (Worker).
A template that could not be tokenized or generated is a page, whatever it started as: it has code the tokenizer saw, and a failure must never be mistaken for something with nothing to compile.
Compilation.TemplateLines
MethodCount(string input)
Parameters
input- The template source.
Returns
MethodPositionOf(string, int)
MethodAdvance(Compilation.TemplatePosition position, string text)
Parameters
position- The position before the text.
text- The text to move past.
Returns
Compilation.TemplatePosition
null, never (0, 0), so it cannot be mistaken for
a real one.
MethodTemplatePosition(int Line, int Column)
null, never (0, 0), so it cannot be mistaken for
a real one.
Parameters
Line- The 1-based line in the template.
Column- The 1-based column in the template.
PropertyLine
PropertyColumn
MethodToString()
Inherited from object.ToString.
Compilation.TemplateScriptSkeleton
0 and spaces so an expression
position stays valid.
MethodCreate(string template)
Parameters
template- The page template as its author wrote it.
Returns
TEMPLATE001 errors and an empty source when the template cannot be tokenized.
Compilation.TemplateShapeCheck
%> can leave a statement open and let
the handler's own closing brace close it; the page compiles and the rest of the template becomes
conditional or literal. These checks are about the template's shape rather than its C#, and they
are warnings: a page that compiles is still served.
MethodCheck(string template)
Parameters
template- The template as its author wrote it.
Returns
Compilation.TemplateSourceGenerator
MethodGenerate(string template)
Parameters
template- The page template.
Returns
MethodGenerateLibrary(string template)
Parameters
template- The library template.
Returns
Exceptions
ArgumentException- The template is not a library. A caller branches on Kind before it asks, so this is a fault in the caller rather than an author's mistake.
Compilation.TemplateTokenizer
MethodTokenize(string input)
Parameters
input- The template as its author wrote it.
Returns
Compilation.Token
MethodToken(Compilation.TokenType Type, string Value, Compilation.TemplatePosition Position, Compilation.TemplatePosition? OpenerPosition)
Parameters
Type- What kind of content the token contains.
Value- The token's content, without its delimiters.
Position- Where the content starts, in template space.
OpenerPosition- Where a write token's opener starts, or
nullotherwise.
PropertyType
PropertyValue
PropertyPosition
PropertyOpenerPosition
null otherwise.Compilation.TokenType
Compilation.TokenizeResult
MethodTokenizeResult(IReadOnlyList<Compilation.Token> Tokens, IReadOnlyList<Compilation.PageDiagnostic> Errors)
Parameters
Tokens- Every token taken from the template before tokenization stopped.
Errors- The problems found, already positioned in template space; empty when the whole template was tokenized.
PropertyTokens
PropertyErrors
PropertyIsSuccess
Diff
Diff.DiffDocument
MethodDiffDocument(IReadOnlyList<Diff.DiffHunk> Hunks, int AddedLines, int RemovedLines, bool IsCoarse)
Parameters
Hunks- The changed regions, in document order; empty when the documents have the same lines.
AddedLines- How many lines the later document adds.
RemovedLines- How many lines the later document removes.
IsCoarse- Whether the documents were too different to align line by line, so the changed middle is one removed block followed by one added block. Every line is still present; the alignment is the part that was given up.
PropertyHunks
PropertyAddedLines
PropertyRemovedLines
PropertyIsCoarse
PropertyIsEmpty
Diff.DiffHunk
MethodDiffHunk(int BeforeStart, int BeforeCount, int AfterStart, int AfterCount, IReadOnlyList<Diff.DiffLine> Lines)
Parameters
BeforeStart- The first before line number the hunk covers, or the line it follows when it covers none.
BeforeCount- How many lines the hunk covers in the earlier document.
AfterStart- The first after line number the hunk covers, or the line it follows when it covers none.
AfterCount- How many lines the hunk covers in the later document.
Lines- The hunk's context, removed and added lines, in document order.
PropertyBeforeStart
PropertyBeforeCount
PropertyAfterStart
PropertyAfterCount
PropertyLines
Diff.DiffLine
MethodDiffLine(Diff.DiffLineKind Kind, string Text, int? BeforeLine, int? AfterLine)
Parameters
Kind- Whether the line is context, added or removed.
Text- The line's text, without its terminator.
BeforeLine- The 1-based line number in the earlier document, or null for an added line.
AfterLine- The 1-based line number in the later document, or null for a removed line.
PropertyKind
PropertyText
PropertyBeforeLine
PropertyAfterLine
Diff.DiffLineKind
FieldContext
FieldAdded
FieldRemoved
Diff.LineDiff
The ordinary case is small: the common prefix and suffix are trimmed first, so one edit in a large page leaves only the lines around it. The middle is then diffed with Myers' O(ND) algorithm. Past MaxEditDistance or MaxLines, the middle becomes one removed block and one added block and IsCoarse says so: every line is still present, but the alignment was given up rather than the work left unbounded.
Lines are what StringReader.ReadLine returns: CRLF, CR and LF are one break, and a final newline terminates the last line rather than creating an empty one. Two templates that differ only in line endings therefore compare equal. The result is pure and has no I/O.
FieldContextLines
FieldMaxEditDistance
FieldMaxLines
MethodCompare(string before, string after)
Parameters
before- The earlier document.
after- The later document.
Returns
Exceptions
ArgumentNullException- Either document is
null.
MethodCompare(string before, string after, int contextLines, bool ignoreSpaceChange)
Parameters
before- The earlier document.
after- The later document.
contextLines- How many unchanged lines surround each changed region.
ignoreSpaceChange-
Whether a run of blanks compares equal to any other run of blanks, and to none at the end of a
line, as
diff -bmeans it to.
Returns
contextLines lines of context.Exceptions
ArgumentNullException- Either document is
null. ArgumentOutOfRangeExceptioncontextLinesis negative.
MethodAsWritten(Diff.DiffDocument, string[], string[])
Diff.NormalDiff
3c3 for a replacement, 3a4,5 for lines added after line 3,
3,4d2 for lines deleted after line 2 — then the earlier document's lines prefixed
< , a --- separator when both sides changed, and the later document's lines
prefixed > . A range is one number when it covers one line and n,m when it covers
more, which is how POSIX writes it, and the letters are the commands ed would take.
MethodToNormal(Diff.DiffDocument diff)
Parameters
diff- The comparison to write.
Returns
Exceptions
ArgumentNullExceptiondiffisnull.
Diff.UnifiedDiff
MethodToUnified(Diff.DiffDocument diff)
Parameters
diff- The comparison to write.
Returns
@@ -a,b +c,d @@ header per hunk followed by lines prefixed with a space, -
or +, or the empty string when nothing changed.
Exceptions
ArgumentNullExceptiondiffisnull.
Markdown
Markdown.LinkPolicy
The assistant renders model output, and model output is influenced by the page source it reads,
so a link is a place a prompt injection could try to send its reader. Only a same-site target —
a relative URL or a fragment — and an absolute http or https URL are allowed.
Everything else is written as its text: javascript:, data:, mailto:,
file:, a protocol-relative //host, a backslash-escaped host and any other scheme.
This is a pure string rule rather than part of the renderer, so the policy is readable and testable without a parser. It is not the page renderer's policy: a page author may write raw HTML and is trusted with whatever a page contains.
MethodIsAllowed(string url)
url a link.Parameters
url- The URL a Markdown link or image named. It is not normalised.
Returns
true for a same-site relative URL, a fragment, or an absolute
http/https URL; otherwise false.
Pages
Pages.PageContentTypeRule
MethodPageContentTypeRule(string MediaType, Pages.PageScriptPolicy ScriptPolicy)
Parameters
MediaType- The response content type, including any parameters.
ScriptPolicy- The response's script policy; None by default.
PropertyMediaType
PropertyScriptPolicy
Pages.PageContentTypes
The extension is the suffix after the last . of the key's last / segment, and only
when there is something before the dot: /app.js is JavaScript, while /app,
/.js and /app.js/child take the fallback. Matching is case-insensitive, so a raw
request path gives the same answer as a canonical key.
The map is a default, not a constraint: a page can still call ctx.Response.SetContentType to send
something else. The script policy deliberately stays with the extension rather than following a
changed content type. Create
validates and throws because the only caller is startup
configuration; ForPath and ScriptsForPath never throw.
PropertyFallback
PropertyFallbackRule
PropertyExtensionCount
MethodCreate(string fallback, IEnumerable<KeyValuePair<string, string>> extensions)
Parameters
fallback- The media type for a key with no mapped extension.
extensions- Extension rows, keyed by the extension including its dot. A row with neither a key nor a value is absent rather than an error; anything else is validated. A string row's script policy is None, which is the old spelling of a row.
Returns
Exceptions
ArgumentException- The fallback, a key or a media type is invalid.
MethodCreate(Pages.PageContentTypeRule fallback, IEnumerable<KeyValuePair<string, Pages.PageContentTypeRule>> extensions)
Parameters
fallback- The rule for a key with no mapped extension.
extensions- Extension rows, keyed by the extension including its dot.
Returns
Exceptions
ArgumentException- The fallback, a key, a media type or a script policy is invalid.
MethodRuleFor(string path)
Parameters
path- A page key or raw request path.
Returns
MethodForPath(string path)
Parameters
path- A page key or raw request path.
Returns
MethodScriptsForPath(string path)
Parameters
path- A page key or raw request path.
Returns
Pages.PageGlob
One segment at a time, as a shell matches a path when globstar is off: * matches any
run of characters inside a segment and never a /, ? matches exactly one character,
and every other character is itself. There is no ** and no bracket expression yet, so
/vim/* names the entries in /vim and nothing below them.
A pattern is matched as a Shell.ShellWord, so a wildcard the caller quoted is the
character: '/vim/*.js' names the one key with a star in it, and /vim/*.js names every
key it fits. Keys are canonical — absolute, lowercase, no empty segments — so a pattern is
normalised as a path first and the two segment lists are compared as they are.
MethodIsMatch(string pattern, string key)
Parameters
pattern- The pattern, as a path a shell would expand.
key- A canonical page key.
MethodIsMatch(Shell.ShellWord pattern, string key)
Parameters
pattern- The word, as the caller wrote it.
key- A canonical page key.
Pages.PageKind
The verdict comes from generation and is stored beside the source, the same way "has code" was: a page is judged by what it contains, so nothing is configured and editing the source can change the kind.
Text is a complete representation and its source, less any comment, is the response; Page renders; Library is only something another page compiles against, so it is never served and never given a render; Worker is a program a page starts, which is also never served.
Generation can only tell that a template has declarations and nothing to render, so it answers Library. Whether those declarations are a worker is a question about types, which only the compiler can answer: a library that declares a public entry point is refined to Worker when it compiles.
FieldText
FieldPage
FieldLibrary
FieldWorker
Pages.PageMode
-rw-r--r-- means a save would be accepted and
-r--r--r-- that it would not, and a folder carries the same answer with a leading
d. The assistant's tools and the virtual shell's ls -l and stat print the
same column, so they ask the same function.
MethodDescribe(bool canWrite)
Parameters
canWrite- Whether a save would be accepted.
MethodDescribeFolder(bool canWrite)
Parameters
canWrite- Whether a save below it would be accepted.
Pages.PagePath
Normalize applies these steps in order:
- A null, empty or whitespace-only path is the root,
/. - The text is lowercased with the invariant culture, so
/Helloand/helloare the same key. - The text is composed to Unicode NFC, so a precomposed accent and a combining accent give the same key.
- The text is split on
/and empty segments are dropped, so leading, trailing and repeated slashes collapse://hello//becomes/hello. .segments are dropped...removes the preceding segment, or is dropped when there is nothing left to remove:/a/../bbecomes/b, and/..becomes/.- A single
/is prefixed, so every key is absolute.
The case fold and the composition are Normalize: folding first and composing last is what leaves the key in NFC, and NFC is what makes two spellings of an accented letter one page.
A key is a path, and a path ends at ? or #: those delimiters can never appear in one,
so IsAddressable is false for a key that contains them and the
shell answers 404 rather than serving a name no URL can produce. Percent-encoding them
instead would be worse, because the canonical comparison is against the decoded request path and
an encoded key would never match it.
Names the routing layer reserves, such as /edit or /error, are not rejected here: the
shell owns the routes, so deciding what a page may not be called belongs there.
PropertyKey
/ unless it is
the root.PropertyIsAddressable
/hello%3Fworld:
the route value is decoded to hello?world, so normalisation faithfully keeps the ?
and the key stops being a path.
MethodNormalize(string path)
Parameters
path- The text to normalise, typically a
pathroute value.
Returns
/ when path is null, empty or
whitespace.MethodToString()
Pages.PageQueryFingerprint
A page that embeds itself with a different query is a recursive component, not a cycle, so the ancestor check compares a page key together with this fingerprint. Two orders of names that a browser could send differently must not collide, and a repeated name keeps the order of its values, so the fingerprint is computed over the ordered list rather than over a dictionary.
Every element is written with its length, so no name or value can be confused with the separators between them.
MethodFingerprint(IEnumerable<KeyValuePair<string, IReadOnlyList<string>>> query)
Parameters
query- Every query value, per name, in order.
Returns
Exceptions
ArgumentNullExceptionqueryis null.
Pages.PageScope
MethodPageScope(Pages.PagePath Path, bool IncludeSelf, bool Recursive)
Parameters
Path- The path the search starts at.
IncludeSelf- Whether the path itself is read, as well as what is below it.
Recursive- Whether everything below the path is read, or only what is directly below.
PropertyPath
PropertyIncludeSelf
PropertyRecursive
MethodContains(Pages.PagePath key)
Parameters
key- The key to test.
Pages.PageScriptPolicy
SetContentType keeps the policy its row declares. The shell writes it as
script-src 'none' or script-src 'self'; inline script and event-handler attributes
stay blocked either way.
FieldNone
FieldSelf
Pages.PageSourceChange
A restore, a seed install and an edit all end in the same comparison, and all three refuse the write that would leave the live source exactly as it is: a revision whose text matches is noise in a history whose job is to record changes (`pages-a-page-may-save-itself`).
A page that is missing or tombstoned has no live source, so bringing it back is a change whatever the text says. The comparison is ordinal because the source is compiled as it was written, so a change of case or of line ending is a different page.
MethodIsNoOp(string live, string chosen)
Parameters
live- The live source, or
nullwhen the page is missing or deleted. chosen- The source a write would store.
Returns
true when the page already holds exactly this text.Pages.PageTree
MethodIsBelow(Pages.PagePath key, Pages.PagePath folder)
Parameters
key- The key to test.
folder- The path to test it against.
Returns
/ab for /a) is another key. Every key but the root is below
the root.
MethodIsDirectlyBelow(Pages.PagePath key, Pages.PagePath folder)
Parameters
key- The key to test.
folder- The path to test it against.
MethodFolderOf(string key)
Parameters
key- A canonical key.
Returns
MethodFoldersAbove(string key)
Parameters
key- A canonical key.
Returns
/a and /a/b
for /a/b/c. A key directly under the root has none, because the root is always there.
Pages.RevisionHash
FieldLength
FieldFormatVersion
MethodIsCanonical(string hash)
Parameters
hash- The value to test.
Returns
MethodOf(string source, string creationRuntimeId, DateTimeOffset savedAt, string revisionId)
Parameters
source- The exact UTF-8 source stored in the revision.
creationRuntimeId- The runtime id captured when the revision was saved.
savedAt- The save instant, normalized to UTC for encoding.
revisionId- The unique shell-generated identifier for this save.
Returns
Pages.SeedComparison
This is the whole seed rule: an automatic write requires H = R and S ≠ R, where R is the seed hash recorded on the page, S is the seed this release ships and H is the content hash of the page's stored source. Everything else is a verdict that says why not.
The two row states — a key with no head row, and a tombstone — are not comparisons and are not decided here: there is nothing to compare, and only the caller knows whether the key is shipped.
MethodSeedComparison(Pages.SeedVerdict Verdict, bool CanApply, bool CanAdopt)
This is the whole seed rule: an automatic write requires H = R and S ≠ R, where R is the seed hash recorded on the page, S is the seed this release ships and H is the content hash of the page's stored source. Everything else is a verdict that says why not.
The two row states — a key with no head row, and a tombstone — are not comparisons and are not decided here: there is nothing to compare, and only the caller knows whether the key is shipped.
Parameters
Verdict- What the row is, relative to the seed.
CanApply- Whether an automatic write may replace the page with the shipped seed: the page still holds the seed it was installed from, and the release has moved the seed on.
CanAdopt- Whether the store may record the shipped seed as installed without writing a revision: the page already holds exactly those bytes, and the record says otherwise.
PropertyVerdict
PropertyCanApply
PropertyCanAdopt
MethodOf(string recorded, string shipped, string content)
Parameters
recorded- R, or
nullwhen the page has no record of a seed. shipped- S, or
nullwhen the release ships no seed for the key. content- H, or
nullwhen the page has no live content.
Returns
Pages.SeedVerdict
FieldInSync
FieldReleaseNewer
FieldEdited
FieldConflict
FieldStoreNewer
FieldUnknown
FieldRetired
Shell
Shell.ShellArgument
MethodShellArgument(Shell.ShellOperandKind Kind, Shell.ShellWord Word)
Parameters
Kind- How the command reads it.
Word- The word itself, quoting and all.
PropertyKind
PropertyWord
Shell.ShellCommandLine
MethodShellCommandLine(IReadOnlySet<char> Flags, IReadOnlyDictionary<char, string> Values, IReadOnlyList<Shell.ShellArgument> Arguments, IReadOnlyList<Shell.ShellWord> Trailing)
Parameters
Flags- The flags, as the letters that were written.
Values- The value options, as the text each was given.
Arguments- The operands, in the order they were written, each with its declared kind.
Trailing- The words the command's own grammar owns, when its syntax allows them.
PropertyFlags
PropertyValues
PropertyArguments
PropertyTrailing
MethodHas(char flag)
Parameters
flag- The letter after the dash.
MethodValue(char letter)
Parameters
letter- The letter after the dash.
MethodNumber(char letter)
Parameters
letter- The letter after the dash.
MethodWords(Shell.ShellOperandKind kind)
Parameters
kind- The kind to take.
Shell.ShellLexResult
MethodShellLexResult(IReadOnlyList<Shell.ShellToken> Tokens, string Error)
Parameters
Tokens- The words and operators, in the order they were written.
Error- A safe message, or null when the line lexed.
PropertyTokens
PropertyError
PropertyWords
PropertyOperator
Shell.ShellLine
A word is a list of Shell.ShellSegments so that quoting survives: a * in a quoted
segment is the character, and a * in an unquoted one is a pattern. Single quotes are literal
throughout, double quotes escape only ", \, $ and a backtick, and a backslash
outside quotes takes the next character literally — a shell's rules, applied one character at a
time.
There is no expansion, so $ and a backtick outside single quotes stop the line rather than
being passed through as data: a caller typing $HOME means expansion, and there is none.
Every fault names help, because a model that guessed a host-shell form should be told where
the accepted one is written down.
MethodLex(string text)
Parameters
text- The line as the caller wrote it.
MethodExpansionError(char)
$ or backtick stops the line.Shell.ShellMatchResult
MethodShellMatchResult(Shell.ShellCommandLine Line, string Error)
Parameters
Line- What was matched, or null when the line was refused.
Error- A safe message, or null when the line matched.
PropertyLine
PropertyError
Shell.ShellOperand
MethodShellOperand(string Name, Shell.ShellOperandKind Kind, int Minimum, int Maximum)
Parameters
Name- What the operand is called in a usage line.
Kind- How the command reads it.
Minimum- How many are required.
Maximum- How many are accepted.
PropertyName
PropertyKind
PropertyMinimum
PropertyMaximum
Shell.ShellOperandKind
FieldText
grep's query.FieldPath
cat's file.FieldPrefix
ls's directory.Shell.ShellOperator
MethodShellOperator(char Character)
Parameters
Character- The character:
|,>,<,&,;, or a line break.
PropertyCharacter
|, >, <, &, ;, or a line break.Shell.ShellSegment
MethodShellSegment(string Text, bool IsLiteral)
Parameters
Text- The characters, with the quote or backslash that made them literal removed.
IsLiteral- Whether a quote or an escape stood in front of them, so that a wildcard among them is the character and not a pattern.
PropertyText
PropertyIsLiteral
Shell.ShellSyntax
-lR), a value may attach
(-n5) or take the next word, -- ends the options, options must lead, and the operand
counts are checked against what was declared. Nothing here knows what a command is called except
through the usage line it is given to quote back.
MethodShellSyntax(IReadOnlyList<char> Flags, IReadOnlyList<Shell.ShellValueOption> Values, IReadOnlyList<Shell.ShellOperand> Operands, bool Trailing)
-lR), a value may attach
(-n5) or take the next word, -- ends the options, options must lead, and the operand
counts are checked against what was declared. Nothing here knows what a command is called except
through the usage line it is given to quote back.
Parameters
Flags- The letters that are flags.
Values- The letters that take a number.
Operands- The operands, in the order they are written.
Trailing-
Whether the command's own grammar continues past its operands, so that words beginning with a dash
are its language rather than a mistake.
find's expression is the reason it exists.
PropertyFlags
PropertyValues
PropertyOperands
PropertyTrailing
find's expression is the reason it exists.
PropertyNothing
MethodMatch(IReadOnlyList<Shell.ShellWord> words, string usage)
Parameters
words- The words of the line, after the command's name.
usage- The command's usage line, quoted in a refusal.
Shell.ShellToken
Shell.ShellValueOption
-n 5, -n5 or -name pattern.MethodShellValueOption(char Letter, string Name, bool Numeric)
-n 5, -n5 or -name pattern.Parameters
Letter- The letter after the dash.
Name- What the value is, in the wording a refusal uses: "a number", "a pattern".
Numeric- Whether the value has to be a number.
PropertyLetter
PropertyName
PropertyNumeric
Shell.ShellWord
MethodShellWord(IReadOnlyList<Shell.ShellSegment> Segments)
Parameters
Segments- The word's runs of characters, in the order they were written.
PropertySegments
PropertyText
PropertyHasWildcard
* or ?.Text
Text.JsonSerialization
System.Text.Json escapes by default for a document: every HTML-significant character
(<, >, &, ' and +) and every non-ASCII character becomes
a \uXXXX escape. That guards JSON written into a web page or a script block, which this site
never does — it writes JSON as a JSON body to a client that parses it, or stores it in SQLite — so
the default only made a page source or a stored value larger than the text it holds.
The relaxed encoder still escapes what JSON itself needs: the quote, the backslash and every control character. "Unsafe" in its name is about embedding the result in HTML, not about JSON validity, and nothing here puts JSON in an HTML context.
Options is a template, not an instance to configure: copy it with
new JsonSerializerOptions(JsonSerialization.Options) before adding a converter or a naming
policy, because the template becomes read-only the first time it is used.
PropertyEncoder
PropertyOptions
Text.LowercaseText
The case mapping runs first so that composing runs last: a case mapping can, in principle, produce a decomposed sequence, and composing afterwards is what makes the result NFC by construction. .NET's invariant mapping is one code point to one code point for every code point it defines, so the reverse order gives the same answer today — but that is a property of the current data rather than of the rule, and the safe order costs nothing.
This is lowercasing, not case folding: ß and ss stay different. Nor is it
compatibility normalisation, so ff stays ff and a fullwidth a stays
fullwidth — the text that comes back is the text that went in, re-encoded. For a path that
matters, because NFKC would turn / into a segment separator and ? into a query
delimiter that no page key may contain.
MethodNormalize(string value)
value with the invariant culture and composes the result
to NFC.Parameters
value- The text to canonicalise. It is not trimmed or validated; the caller owns what a valid key is.
Returns
value.Exceptions
ArgumentNullExceptionvalueis null.ArgumentExceptionvalueis not valid Unicode.
Text.MessageText
A page path, tool name or argument name is data a model or an owner wrote, so quoting it back in a message is quoting untrusted text: it may carry line breaks that fake a new message, control characters, or bidi overrides that make a value read as something else. Every run of whitespace collapses to a single space, everything that cannot be printed is dropped, and the result stops at MaximumLength text elements, ending in Ellipsis when it was shortened.
Truncation counts text elements rather than UTF-16 code units so a surrogate pair, a combined accent or an emoji is never cut in half; the code-unit cap keeps one pathological cluster — a base character followed by thousands of combining marks — from defeating the limit. Dropping an unpaired surrogate keeps the result valid Unicode, which is what Normalize and string.Normalize require.
FieldMaximumLength
FieldEllipsis
MethodSanitize(string value)
value into one line of at most
MaximumLength text elements.Parameters
value- The untrusted text to quote. It is neither validated nor preserved.
Returns
Exceptions
ArgumentNullExceptionvalueis null.