The host's pure half

All assemblies · uk.osric.asp.Core · 131 types · 648 entries

Assistant

Assistant.AccountBalance

A provider account's balance, as the provider's balance endpoint reports it.

MethodAccountBalance(bool IsAvailable, IReadOnlyList<Assistant.CurrencyBalance> Currencies)

A provider account's balance, as the provider's balance endpoint reports it.

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

Whether the provider says the balance can fund API calls.

PropertyCurrencies

The balance in each currency the provider reports, in its own order.

Assistant.AccountBalanceAmounts

Reads the provider's money strings as numbers.
The figures arrive as text the provider already formatted, and a gauge takes a number. The parse is invariant-culture and decimal, so a figure is read the same way wherever the site runs and no rounding happens between the provider and the meter.

MethodTryRead(string total, ref decimal amount)

Reads one currency's total from the text the provider sent.

Parameters

total
The provider's figure, such as 110.00.
amount
The figure, when the text is one.

Returns

Whether the text was a figure.

Assistant.AccountBalanceJson

Reads the provider's balance response without depending on anything but the text.
The figures stay the provider's own strings: they are money it already formatted, and rounding or reformatting them would put a second opinion between the reader and the account. A malformed entry is skipped rather than guessed at, so one bad line does not cost the rest of the response.

MethodParse(string json)

Parses the JSON body the provider's balance endpoint returns.

Parameters

json
The response body.

Returns

The reported balance, which may name no currencies.

Exceptions

JsonException
The body is not valid JSON.
FormatException
The body is valid JSON but not an object.

Assistant.AccountBalanceRead

The outcome of reading a provider account's balance: the figures, or the reason there are none.
A failure is a value rather than a log entry, because the conversation page and the sampler want different things from the same read: the page shows one sentence for any failure, and the sampler logs when the reason changes rather than once per attempt.

PropertyBalance

The provider's figures, or null when the read produced no balance.

PropertyReason

Why the read produced the balance or did not.

MethodOk(Assistant.AccountBalance balance)

A read that produced the provider's figures.

Parameters

balance
The provider's figures.

Returns

The read.

MethodFailed(Assistant.AccountBalanceReason reason)

A read that produced no balance.

Parameters

reason
Why there are no figures; Ok is refused.

Returns

The read.

Exceptions

ArgumentOutOfRangeException
The reason says a balance was read.

Assistant.AccountBalanceReason

Why a balance read produced the provider's figures or did not.

FieldOk

The provider answered with a balance.

FieldUnsupported

The provider has no balance route, so it answered 404.

FieldError

The provider answered with an error status other than 404.

FieldTimeout

The provider did not answer before the deadline.

FieldUnreachable

The provider could not be reached at all.

FieldInvalid

The provider's body was not the balance JSON.

Assistant.ApprovalMode

Controls whether tools marked for approval pause before execution.

FieldAlwaysApprove

Run flagged tools without an owner prompt.

FieldRequireApproval

Wait for an owner decision for each flagged tool call.

Assistant.BudgetAmount

Formats a budget figure to at most three digits and a unit letter, so a gauge stays one short line however much a run has spent.
The conversation page draws seven figures in two columns and repeats each one over its meter. A raw figure such as 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)

Formats value as a compact figure such as 16k.

Parameters

value
The figure to format, which may not be negative.

Returns

The figure with a unit letter only when it is at least a thousand.

MethodFormat(double value)

Formats a measured value as at most three significant figures and a unit letter.

Parameters

value
The figure to format; it may be negative.

Returns

The figure with a unit letter from a thousand upwards, and up to three significant figures below it, so an axis tick reads 1.2k or 0.25 rather than 1.048576e+06.

Assistant.BudgetSnapshot

What a conversation has spent of each assistant budget the page shows.

MethodBudgetSnapshot(long ContextTokens, int Steps, int ToolCalls, int LongestArguments, int LongestResult, int LastCompletionTokens, long Window, int MaxTokens, int LastMaxTokens, long EstimateError)

What a conversation has spent of each assistant budget the page shows.

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

The estimated tokens of the provider request the plan would send.

PropertySteps

The steps the current or most recent run has taken.

PropertyToolCalls

The tool calls that run has made.

PropertyLongestArguments

The longest serialized tool-call arguments in the transcript.

PropertyLongestResult

The longest stored tool result in the transcript.

PropertyLastCompletionTokens

The most recent completion tokens the provider reported.

PropertyWindow

The model's whole context window, as the provider reported it.

PropertyMaxTokens

The reply allowance the planned request would be sent with.

PropertyLastMaxTokens

The allowance the last step's request was sent with.

PropertyEstimateError

How far the last step's estimate was from the provider's count: positive when the estimate was high, negative when it was low.

PropertyEmpty

The figures before anything has been spent.

PropertyEstimateErrorMagnitude

How far the estimate missed, without its direction.

PropertyEstimateDirection

Whether the estimate was high, which is the safe direction, or low.

PropertyWindowUsed

The context and the reply together, which is what the window is compared against.

MethodMeasure(Assistant.ContextPlan plan, IReadOnlyList<Assistant.ChatMessage> stored, int steps, int toolCalls, int? lastCompletionTokens, int? lastMaxTokens, Assistant.ContextBudget budget, long estimateError)

Measures a plan against the transcript it was built from.
Masking changes the request, not the cap a stored call or result had to satisfy, so the longest argument and result rows read the stored transcript and keep showing the real stored values.

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

The figures, with the counters carried through unchanged.

Assistant.ChatMessage

A provider message used by the pure context-budgeting rules.

MethodChatMessage(string Role, string Content, string ToolCallsJson, string ToolCallId, string ToolName)

A provider message used by the pure context-budgeting rules.

Parameters

Role
The chat role, such as system, user, assistant or tool.
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

The chat role, such as system, user, assistant or tool.

PropertyContent

The plain-text message content.

PropertyToolCallsJson

Complete assistant tool-call data, when present.

PropertyToolCallId

The tool-call id for a tool result.

PropertyToolName

The tool name for a tool result.

Assistant.ChatRequest

A provider request expressed only in framework-independent values.

MethodChatRequest(string Model, IReadOnlyList<Assistant.ChatMessage> Messages, IReadOnlyList<Assistant.ToolDefinition> Tools, double Temperature, int MaxTokens, string ReasoningField)

A provider request expressed only in framework-independent values.

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

The configured model name.

PropertyMessages

The ordered transcript for this step.

PropertyTools

The available functions.

PropertyTemperature

The configured sampling temperature.

PropertyMaxTokens

The provider's own max_tokens, computed for this request.

PropertyReasoningField

The provider field name used for optional reasoning deltas.

Assistant.ChatRequestJson

The one serializer for the provider's chat-completions body, and the one measure of it.
The client sends exactly what Serialize returns, and every budget figure counts exactly that body, so a field added here moves the request and the meter together. It is pure: it parses the stored tool-call and parameter JSON, builds the body, and serializes it, with no I/O and no state.

MethodSerialize(Assistant.ChatRequest request)

Builds the JSON body the provider receives.

Parameters

request
The request to serialize.

Returns

The body, as UTF-8 text.

MethodMeasureMessage(Assistant.ChatMessage message)

Measures one message as the body carries it, in UTF-8 bytes.
The planner sizes each message once and then adds and subtracts those figures as it masks and drops, so this is the one place a message's cost is counted.

Parameters

message
The message to measure.

Returns

The byte count of the message's own JSON object.

MethodMeasureBytes(Assistant.ChatRequest request)

Measures the body the provider receives, in UTF-8 bytes.
This is the single place a request's size is counted: the planner, the trimmer and the page all ask here rather than building their own figure. A token budget estimates tokens from this byte count with Assistant.TokenEstimator, calibrated by the provider's last report, and leaves the rules alone.

Parameters

request
The request to measure.

Returns

The byte count of Serialize.

Assistant.ChatResponse

The accumulated values from one provider response.

MethodChatResponse(string, string, IReadOnlyList<Assistant.ToolCall>, string, Assistant.TokenUsage)

The accumulated values from one provider response.

PropertyHasContent

Whether the provider emitted user-visible or actionable data.

Assistant.ChatStreamAccumulator

Combines provider deltas into one complete assistant response.

MethodAdd(Assistant.ChatStreamEvent event)

Adds one provider event to the current response.

Parameters

event
The provider event.

MethodComplete()

Returns the current complete response without changing the accumulator.

Assistant.ChatStreamEvent

One event emitted while a provider streams a completion.
Closed: a provider emits one of these five, and nothing outside this assembly may add a sixth, so a matcher can rely on the set.

Assistant.ContentDelta

A fragment of assistant response text.

MethodContentDelta(string)

A fragment of assistant response text.

Assistant.ContextBudget

The one content budget: the model's reported window and the reply reserved from it.
The provider reports the window and the largest reply the model accepts; the operator chooses only the floor under a reply, so the prompt's share is the window less that floor. Every other content cap is a fraction of the prompt budget rather than a number standing beside it, so no single payload can fill the budget the planner is protecting (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

The conservative bytes one token costs, which is the densest content the spike measured.

FieldMinimumPromptTokens

The least prompt a window must leave room for; a smaller one is a configuration mistake.

PropertyContextWindow

The window the provider reported, counting both the prompt and the reply.

PropertyMaximumOutputTokens

The largest max_tokens the provider accepts for this model.

PropertyMinimumOutputTokens

The floor under a reply, which is the only part of the split an operator chooses.

PropertyPromptBudget

The prompt's share of the window: everything except the reply's floor.

PropertyToolResultChars

The most characters one tool result may carry, an eighth of the prompt budget.

PropertyMessageChars

The most characters the owner's message may carry, an eighth of the prompt budget.

PropertyMemoryCharsPerRun

The most characters a run's memory block may cost, a thirty-second of the prompt budget.

MethodCreate(long contextWindow, int maximumOutputTokens, int minimumOutputTokens)

Resolves a reported window and the configured floor into the budget a run is given.

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

The budget, with the prompt's share and its fractions resolved.

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)

Builds a budget from a prompt share, for a test that is about the arithmetic.

Parameters

promptTokens
The share of the window the prompt may spend.
maximumOutputTokens
The largest reply the provider accepts.

Returns

A budget whose prompt share is exactly promptTokens.

MethodMaxTokens(long estimatedPrompt)

The max_tokens a request estimated at estimatedPrompt is sent with.
The estimate carries the margin, so a low estimate shortens the reply's allowance by the same amount: the prompt and the reply together stay inside the window rather than needing a haircut.

Parameters

estimatedPrompt
The prompt's estimated size, including the estimate's margin.

Returns

What the window leaves, capped at the published maximum and floored at the configured minimum.

PropertyEstimateMargin

The error a step's estimate may carry before it has spent the margin.

Returns

The margin in tokens, which is the prompt budget times the estimator's margin over one.

Assistant.ContextPlan

The request to send and what it took to fit it into the budget.

MethodContextPlan(Assistant.ChatRequest Request, int MaskedToolResults, int MaskedArguments, int DroppedMessages, long OriginalTokens, long EstimatedTokens, long RequestBytes, string Error)

The request to send and what it took to fit it into the budget.

Parameters

Request
The request the provider is sent, with its max_tokens resolved.
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 Request as 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

The request the provider is sent, with its max_tokens resolved.

PropertyMaskedToolResults

How many old tool results were replaced with placeholders.

PropertyMaskedArguments

How many long argument strings were elided.

PropertyDroppedMessages

How many transcript messages were dropped with their turns.

PropertyOriginalTokens

The request's estimated size before anything was masked or dropped.

PropertyEstimatedTokens

The estimated size of Request as it will be sent.

PropertyRequestBytes

The exact UTF-8 bytes of Request, for calibration.

PropertyError

Why no request can fit, when even the smallest one is too large.

PropertyIsMasked

Whether any old tool result or argument payload was elided.

PropertyIsTrimmed

Whether any whole turn was dropped.

PropertyMaxTokens

The max_tokens the planned request is sent with.

Assistant.ContextPlanner

Fits a request into a token budget: mask old payloads first, then drop whole turns.
Masking runs first because it loses less: it keeps every user and assistant word, the tool names and the short arguments, and gives up only old payloads. The trimmer is the fallback for a conversation whose old reasoning is the bulk. A request that is already inside the budget is returned untouched, so the common step keeps its prefix byte-identical and the provider's prompt cache intact.

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)

Builds the request to send, fitting it into 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

The plan, with the request to send, what changed, and any error.

Assistant.ContextTrimResult

The result of fitting whole conversation turns into a token budget.

MethodContextTrimResult(Assistant.ChatRequest Request, int DroppedMessages, long EstimatedTokens, long RequestBytes, string Error)

The result of fitting whole conversation turns into a token budget.

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 Request as 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

The smallest request that was built: system prompt plus the turns kept.

PropertyDroppedMessages

How many transcript messages were omitted.

PropertyEstimatedTokens

The estimated size of Request as it would be sent.

PropertyRequestBytes

The exact UTF-8 bytes of Request, for calibration.

PropertyError

A safe reason no request can be built, when the newest turn cannot fit.

PropertyIsTrimmed

Whether older conversation messages were omitted.

PropertyTrimmingNote

A display-safe note to include when the request omitted earlier turns.

Assistant.ContextTrimmer

Fits a request to a token budget by dropping the oldest whole turns.
Each message is measured once and the turns are summed from those figures, so building a candidate is arithmetic rather than a serialization. The whole-turn rule is unchanged: a turn is never split from its tool calls or results, and the newest turn is the smallest request there is.

MethodTrim(Assistant.ChatRequest request, long maximumTokens, Assistant.TokenEstimator estimator)

Keeps the system prompt and the newest whole turns that fit.

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

The smallest request that fits, or the newest turn with an error when that cannot.

Assistant.ConversationSplit

A transcript split into its system prompt and whole conversation turns.

MethodConversationSplit(Assistant.ChatMessage System, IReadOnlyList<IReadOnlyList<Assistant.ChatMessage>> Turns)

A transcript split into its system prompt and whole conversation turns.

Parameters

System
The system prompt when the transcript starts with one.
Turns
Whole turns, oldest first, each beginning at a user message.

PropertySystem

The system prompt when the transcript starts with one.

PropertyTurns

Whole turns, oldest first, each beginning at a user message.

Assistant.ConversationTitle

Builds a compact title from the first line of a conversation's first message.

FieldNewConversation

The title shown before a conversation has a user message.

FieldMaximumLength

The maximum title length accepted by storage and the UI.

MethodFrom(string message)

Creates a whitespace-normalised title, truncated at a word boundary when possible.

Parameters

message
The first user message.

Returns

The first line, or NewConversation when that line is blank.

Assistant.ConversationTurns

The whole-turn rule the trimmer keeps: a turn is never split from its tool calls or results.

MethodSplit(IReadOnlyList<Assistant.ChatMessage> messages)

Splits a transcript into its system prompt and whole turns.
Only a leading 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

The system prompt, when present, and the turns.

MethodFlatten(Assistant.ChatMessage system, IEnumerable<IReadOnlyList<Assistant.ChatMessage>> turns)

Rebuilds a transcript from the system prompt and the turns that were kept.

Parameters

system
The system prompt, when the transcript had one.
turns
The turns to keep, oldest first.

Returns

The messages, in provider order.

Assistant.CurrencyBalance

One currency's balance, with the provider's own figures.

MethodCurrencyBalance(string Currency, string Total, string Granted, string ToppedUp)

One currency's balance, with the provider's own figures.

Parameters

Currency
The currency code the provider reports, such as CNY or USD.
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

The currency code the provider reports, such as CNY or USD.

PropertyTotal

The total available balance, including granted and topped-up credit.

PropertyGranted

The granted balance that has not expired.

PropertyToppedUp

The balance the owner has paid in.

Assistant.Finished

The provider's completion reason for a stream step.

MethodFinished(string)

The provider's completion reason for a stream step.

Assistant.GrepPattern

A grep query, as the matcher that runs it.

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)

Compiles a query, or explains why it cannot be one.

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)

Whether a line of page source matches.

Parameters

line
One line, without its line break.

Exceptions

ArgumentNullException
line is null.

MethodTryTranslate(string, ref string, ref string)

Rewrites a basic regular expression into the form Regex reads.
The whole of the difference is which characters are syntax: |, (, ), {, }, + 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)

Copies a character class, from its opening bracket to its closing one.

Assistant.MaskOutcome

The outcome of offering one message to the masker.

MethodMaskOutcome(Assistant.ChatMessage Message, int MaskedResults, int MaskedArguments)

The outcome of offering one message to the masker.

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

The message to send: the original when nothing was elided.

PropertyMaskedResults

1 when a tool result was replaced with a placeholder.

PropertyMaskedArguments

How many long argument strings were elided.

PropertyChanged

Whether anything in the message changed.

Assistant.MemoryCandidate

One memory as recall, the tools and the owner's page see it: the head row, without its history.

MethodMemoryCandidate(long Id, Assistant.MemoryKind Kind, string Content, int Version, DateTimeOffset Written, DateTimeOffset? LastUsed, int RecallCount, bool Pinned, long? SourceConversationId)

One memory as recall, the tools and the owner's page see it: the head row, without its history.

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

The memory's id, which is what a tool call names and the block labels.

PropertyKind

What kind of note it is.

PropertyContent

The note's text, already normalised.

PropertyVersion

The version a later update or edit has to carry to be accepted.

PropertyWritten

When this version was written.

PropertyLastUsed

When it was last recalled, or null when it never was.

PropertyRecallCount

How many runs have recalled it.

PropertyPinned

Whether the owner pinned it, which only the owner may change.

PropertySourceConversationId

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.

Assistant.MemoryContent

Normalises and validates the text of a memory before it is stored.
A memory is one note, not a document: its whitespace is collapsed so the same note written twice compares equal, and one that is too long is refused rather than truncated, because a truncated memory is a sentence the model never wrote.

MethodNormalise(string content, int maximumChars)

Trims, collapses whitespace and checks the length.

Parameters

content
The model-supplied text.
maximumChars
The configured length cap, in characters.

Returns

The normalised text, or the refusal.

MethodSameNote(string left, string right)

Whether two normalised memories are the same note.

Parameters

left
One normalised memory.
right
Another normalised memory.

Returns

Whether they differ only in case.

Assistant.MemoryContentResult

The text of a memory, normalised, or the reason it cannot be stored.

MethodMemoryContentResult(string Content, string Error)

The text of a memory, normalised, or the reason it cannot be stored.

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

The normalised text, or the empty string when the content was refused.

PropertyError

A sentence the model can act on, or null when the content is usable.

PropertyIsSuccess

Whether the content may be stored.

MethodRefused(string error)

A refusal the caller can hand straight back as a tool result.

Parameters

error
Why the content was refused.

Returns

The result.

Assistant.MemoryGroup

One kind's memories, as the owner's page draws them.

MethodMemoryGroup(Assistant.MemoryKind Kind, IReadOnlyList<Assistant.MemoryCandidate> Memories)

One kind's memories, as the owner's page draws them.

Parameters

Kind
The kind the heading names.
Memories
Its memories, pinned first and newest change first after that.

PropertyKind

The kind the heading names.

PropertyMemories

Its memories, pinned first and newest change first after that.

Assistant.MemoryKind

What kind of note a memory is.
Four values, not a taxonomy: enough to group the block the model reads and to make the owner's page (IDEA-023) useful, and small enough that the model is not choosing between neighbours.

FieldPreference

How the owner wants things done.

FieldFact

Something durable about this site or the setup it runs on.

FieldFeedback

A correction the owner gave.

FieldReference

Where something lives.

Assistant.MemoryKinds

Names and parses the four Assistant.MemoryKind values.

PropertyAll

Every kind, in the order the prompt lists them.

MethodName(Assistant.MemoryKind kind)

The stored and provider-visible name of a kind: its lower-case name.

Parameters

kind
The kind to name.

Returns

The name the database column and the tool schema use.

MethodTryParse(string text, ref Assistant.MemoryKind kind)

Parses a model-supplied or stored kind name.

Parameters

text
The name, matched case-insensitively.
kind
The kind, when the name is one of the four.

Returns

Whether the name was a kind.

MethodParse(string text)

Parses a stored kind name, falling back to Fact.

Parameters

text
The stored name.

Returns

The kind the row names, or Fact when it names none.

Assistant.MemoryListing

The order the owner's page lists memories in.
The rule is pure so the page has nothing to decide: the four kinds in their own order, a kind with nothing in it left out, and inside a kind the pinned memories first — the owner asked for those by pinning them — then the newest change. The id breaks a tie, so two memories written in the same instant keep one order between two renders.

MethodGroup(IReadOnlyList<Assistant.MemoryCandidate> memories)

Groups a listing by kind and orders each group.

Parameters

memories
The owner's memories, in any order.

Returns

One group per kind that has memories, in kind order.

Assistant.MemoryQuery

Turns a message into the FTS5 expression a recall matches with.
The expression is built from the owner's own words, so it is sanitised by construction: a term is letters and digits only, quoted, with a trailing *. 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

The shortest term worth searching for.

MethodTerms(string message, int maximum)

The quoted prefix terms a message is searched with.

Parameters

message
The newest user message.
maximum
The most terms to keep, matching the configured query-term cap.

Returns

A space-separated FTS5 expression, or the empty string when the message has no usable term.

Assistant.MemoryRecall

Chooses the memories one run is given, and writes the block they appear in.
Both halves are pure: the store supplies candidates and the run supplies the caps, so the rule that decides what the model sees can be read and tested without a database. The block is escaped on the way out, because a memory is text the model wrote earlier and must not be able to close its own element or forge another.

FieldTagAllowance

What a memory costs beyond its content: the tags that carry its id, kind, date and use count, plus the closing tag and the line breaks.

MethodSelect(IReadOnlyList<Assistant.MemoryCandidate> pinned, IReadOnlyList<Assistant.MemoryCandidate> used, IReadOnlyList<Assistant.MemoryCandidate> query, int maximumChars)

Picks the memories that fit, in the order the block lists them.
Pinned memories come first because the owner asked for them by pinning them; then the ones this conversation already used, which is what keeps a follow-up turn on the same subject; then the query's best matches. An id already taken is skipped, and selection stops at the first memory that does not fit, so the order is the priority rather than a later pass over a worse one.

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

The chosen memories, their cost, and whether anything was left out.

MethodBuild(Assistant.MemorySelection selection)

Writes the prompt block for a selection.

Parameters

selection
The memories one run was given.

Returns

The block, or the empty string when nothing was selected: an empty heading would be an invitation to invent a memory.

Assistant.MemorySecrets

Refuses a memory that looks like a secret, best-effort, with the rule that refused it.
This is a guard, not a sanitiser: it exists because the model is told never to store a secret and a prompt is not a guarantee. It has to let a sentence about a secret through — "the API key lives in the deployment environment" is exactly the kind of note worth keeping — so it looks for the shapes a secret is written in rather than the words around it.

FieldPrivateKey

The rule names the refusal quotes.

FieldAssignment

The rule name for an assignment to a credential-shaped name.

FieldProviderKey

The rule name for a provider-shaped key.

FieldEncodedValue

The rule name for a long base64-like run.

MethodLooksLikeSecret(string content)

The rule a memory's text looks like a secret by, or null when it looks like prose.

Parameters

content
The normalised text of a memory.

Returns

The name of the first rule that matched, or null.

Assistant.MemorySelection

What one run's recall chose, and what it cost.

MethodMemorySelection(IReadOnlyList<Assistant.MemoryCandidate> Memories, int Characters, bool Truncated)

What one run's recall chose, and what it cost.

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

The chosen memories, in the order the block lists them.

PropertyCharacters

What the block costs: each memory's content and its tag allowance.

PropertyTruncated

Whether a candidate that fitted the count did not fit the characters.

PropertyIsEmpty

Whether the run was given no memory at all.

Assistant.PageLineEdit

One replacement of inclusive physical template-source lines.

MethodPageLineEdit(int StartLine, int EndLine, string Replacement, string ExpectFirst, string ExpectLast)

One replacement of inclusive physical template-source lines.

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

The first 1-based physical line to replace.

PropertyEndLine

The last 1-based physical line to replace, inclusive.

PropertyReplacement

The replacement source, which may contain line breaks.

PropertyExpectFirst

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.

PropertyExpectLast

The exact text the last line must still hold, or null to accept whatever is there.

Assistant.PageRangeEditResult

The result of replacing a bounded 1-based range of page lines.

MethodPageRangeEditResult(string Content, string Error)

The result of replacing a bounded 1-based range of page lines.

Parameters

Content
The new source, or null when validation failed.
Error
A safe validation error, or null when replacement succeeded.

PropertyContent

The new source, or null when validation failed.

PropertyError

A safe validation error, or null when replacement succeeded.

PropertyIsSuccess

Whether the replacement is valid.

Assistant.PageRangeEditor

Replaces inclusive physical lines of stored template source without changing surrounding bytes.
Lines are counted before template tokenization, C# generation, or HTML rendering. Literal HTML, code, and template delimiters all occupy lines exactly where they appear in the stored source. CRLF is one line break; bare CR and LF are each one. A final line break creates an empty final line.

MethodReplace(string source, int startLine, int endLine, string replacement, int maximumChars)

Replaces the selected lines and refuses invalid ranges or oversized output.

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)

Replaces the selected lines when they still hold the text the caller expected.

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)

Applies several line replacements as one edit, refusing overlapping ranges or oversized output.

Parameters

source
The complete current page source.
edits
The replacements, whose line numbers all refer to source.
maximumChars
The maximum resulting source length.

Returns

The source with every edit applied, or a refusal. The edits are applied from the bottom up, so one replacement's line numbers do not shift another's.

Assistant.PageWrites

Reads which page a write or edit tool reported it changed.
Only the stored tool result is consulted, because that is what the run left behind: a call that was refused, or one whose arguments only named a page a later check rejected, changed nothing. The result envelope is the assistant's own ({"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)

The page a successful write or edit reported.

Parameters

changesPages
Whether the tool changes a stored page, as the tool itself says.
resultJson
The stored result of that call.

Returns

The canonical key of the changed page, or null when the call was not a page write, did not succeed, or named a key no request can address.

Assistant.PromptSizes

Each message's serialized size, measured once, and the arithmetic over those figures.
Masking one payload and dropping one turn are both changes to a known part of the body, so the planner and the trimmer add and subtract sizes instead of serializing every candidate they build. The body is the fixed part — model, tools, sampling fields and the array brackets — plus the messages separated by commas, so the fixed part is whatever the exact measure leaves over.

PropertySizes

Each message's serialized size, in the request's own order.

PropertyTotal

The exact bytes of the request as it was measured.

MethodMeasure(Assistant.ChatRequest request)

Measures each message of a request once.

Parameters

request
The request to measure.

Returns

The sizes, and the fixed part of the body they are added to.

MethodBody(long messageBytes, int count)

The body the same request would cost with this message sum and count.

Parameters

messageBytes
The summed sizes of the messages kept.
count
How many messages are kept.

Returns

The exact byte count the body would have.

MethodSizeOf(Assistant.ChatMessage message)

The size of a message this instance measured.

Parameters

message
A message from the measured request.

Returns

The message's serialized size.

MethodOf(IReadOnlyList<Assistant.ChatMessage> messages)

The body the same request would cost carrying exactly these messages.

Parameters

messages
The messages to carry.

Returns

The exact byte count the body would have.

Assistant.ReasoningDelta

A fragment of provider-supplied reasoning, kept display-only by the host.

MethodReasoningDelta(string)

A fragment of provider-supplied reasoning, kept display-only by the host.

Assistant.RunUsage

What a run has spent, accumulated over its steps.

MethodRunUsage(int PromptTokens, int CompletionTokens, int CachedTokens, int ReasoningTokens, int LastCompletionTokens)

What a run has spent, accumulated over its steps.

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

Every step's prompt tokens added together.

PropertyCompletionTokens

Every step's completion tokens added together.

PropertyCachedTokens

Every step's cache-hit prompt tokens added together.

PropertyReasoningTokens

Every step's reasoning completion tokens added together.

PropertyLastCompletionTokens

The most recent step's completion tokens, which the completion budget counts.

PropertyEmpty

The figures before anything has been spent.

PropertyTotalTokens

The prompt and completion tokens together; cached and reasoning are already inside them.

MethodAdd(Assistant.TokenUsage usage)

Adds one step's report, keeping the same rule the store uses.

Parameters

usage
The step's report, or null when the provider did not send one.

Returns

The totals, with the last completion figure replaced only when this step reported one.

Assistant.TokenCalibration

What the provider's last report says about the request it counted.

MethodTokenCalibration(long RequestBytes, int PromptTokens)

What the provider's last report says about the request it counted.

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

The exact UTF-8 bytes of the request that report describes: the anchor.

PropertyPromptTokens

The prompt tokens the provider reported for that request.

PropertyIsUsable

Whether both figures are positive and a ratio can be taken.

PropertyBytesPerToken

The bytes one prompt token cost, as the last report measured it.

Assistant.TokenEstimator

Estimates a request's token count from the provider's own count of the last one.
The provider counts every request it receives and reports the figure, so the estimate is anchored on that exact count and only the bytes appended since are estimated. The margin therefore covers the delta's ratio error rather than the whole conversation, and each step's report corrects the next (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

The conservative ratio used before the provider has reported anything.

FieldDeltaMargin

How much the estimate is raised above the calibrated ratio; it covers the delta only.

FieldMinimumBytesPerToken

The densest ratio a report may imply; below this the estimate is clamped.

FieldMaximumBytesPerToken

The cheapest ratio a report may imply; above this the estimate is clamped.

MethodTokenEstimator(double bytesPerToken, double margin)

Builds an estimator from a ratio, clamped to the range the spike measured.

Parameters

bytesPerToken
The bytes one token is expected to cost.
margin
How much to raise the estimate; one means no margin.

PropertyBytesPerToken

The bytes one token is expected to cost.

PropertyMargin

How much the estimate is raised above the calibrated ratio.

PropertyAnchor

The request the provider last counted, or null when it has counted none.

MethodFor(Assistant.TokenCalibration calibration)

Builds the estimator a provider report supports, anchored on that report.

Parameters

calibration
The last request's bytes and prompt tokens, or null when there is none.

Returns

An estimator whose ratio is the calibration's, clamped, or the default.

MethodEstimate(Assistant.ChatRequest request)

Estimates the tokens a request would cost.

Parameters

request
The request whose serialized body is measured.

Returns

The estimated prompt tokens, including the margin.

MethodEstimate(long requestBytes)

Estimates the tokens a request body of this size would cost.

Parameters

requestBytes
The UTF-8 bytes of the serialized body.

Returns

The estimated prompt tokens, including the margin.

Assistant.TokenUsage

Provider token counts, when available.

MethodTokenUsage(int? PromptTokens, int? CompletionTokens, int? CachedTokens, int? ReasoningTokens)

Provider token counts, when available.

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

The input tokens the provider reported.

PropertyCompletionTokens

The output tokens the provider reported.

PropertyCachedTokens

The prompt tokens the provider served from its cache, when it says.

PropertyReasoningTokens

The completion tokens spent on reasoning, when the provider says.

Assistant.ToolArgumentSchema

One allowed argument in a tool schema.

MethodToolArgumentSchema(string Name, Assistant.ToolArgumentType Type, bool Required)

One allowed argument in a tool schema.

Parameters

Name
The exact property name.
Type
The JSON value type.
Required
Whether the property must be present.

PropertyName

The exact property name.

PropertyType

The JSON value type.

PropertyRequired

Whether the property must be present.

PropertyItems

The properties of each element when Type is Array; null for every other type.

Assistant.ToolArgumentType

The JSON value kind accepted by one tool argument.

FieldString

A JSON string.

FieldInteger

A signed 32-bit JSON integer.

FieldBoolean

A JSON boolean.

FieldArray

A JSON array of objects whose properties Items describes.

Assistant.ToolArguments

Validates strict, bounded JSON objects used as tool arguments.

MethodParse(string json, IReadOnlyList<Assistant.ToolArgumentSchema> schema, int maximumChars)

Parses an object against an explicit allow-list and type schema.

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

A validated argument object or a safe validation error.

MethodToolArgumentsResult(IReadOnlyDictionary<string, JsonElement> Values, string Error)

A validated argument object or a safe validation error.

Parameters

Values
Cloned JSON values for the declared properties.
Error
A safe validation failure, or null when valid.

PropertyValues

Cloned JSON values for the declared properties.

PropertyError

A safe validation failure, or null when valid.

PropertyIsSuccess

Whether the argument object passed validation.

Assistant.ToolCall

A complete provider tool call, ordered by its stream index.

MethodToolCall(int, string, string, string)

A complete provider tool call, ordered by its stream index.

Assistant.ToolCallDelta

A fragment of one indexed tool call.

MethodToolCallDelta(int, string, string, string)

A fragment of one indexed tool call.

Assistant.ToolDefinition

A function tool offered to the configured chat-completions provider.

MethodToolDefinition(string Name, string Description, bool NeedsApproval, string ParametersJson)

A function tool offered to the configured chat-completions provider.

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

The stable tool name.

PropertyDescription

The provider-visible description.

PropertyNeedsApproval

Whether RequireApproval mode pauses before execution.

PropertyParametersJson

The JSON Schema object for the tool arguments.

Assistant.ToolResultMasker

Replaces old tool results and old argument payloads in a request with placeholders.
This is a derived, per-request rule: the stored transcript is never rewritten. Nothing is exempt: masking walks oldest first, so the newest payloads are the last to be given up, and it stops the moment the request fits. A count would add an exemption that can bite back — eight protected results are more tokens than the whole budget — and the order already says what matters (assistant-old-tool-results-are-masked).

FieldMaximumArgumentLength

The longest argument string a request may carry once a call has been masked.

FieldMaximumArgumentDepth

How far into a nested argument object the masker walks.

MethodMaskableMessages(IReadOnlyList<Assistant.ChatMessage> messages)

Finds the messages the masker may shorten, oldest first.

Parameters

messages
The request's messages, in provider order.

Returns

The indices that masking would change. The order is the stored sequence order.

MethodMask(Assistant.ChatMessage message)

Masks one message's payloads.

Parameters

message
The message to offer to the masker.

Returns

The message to send and what was elided.

Assistant.UsageEvent

A usage event from the provider.

MethodUsageEvent(Assistant.TokenUsage)

A usage event from the provider.

Charting

Charting.ChartAxis

A chart's value axis: a title and the ticks drawn along it.

MethodChartAxis(string Title, IReadOnlyList<Charting.ChartTick> Ticks, double Divisor)

A chart's value axis: a title and the ticks drawn along it.

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

What the axis measures, for the chart's description.

PropertyTicks

The ticks, in any order; the chart sorts them by position.

PropertyDivisor

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.

MethodScale(double? value)

Rescales a sample into the axis' unit, keeping a gap a gap.

Parameters

value
The sample, in the unit it was recorded in.

Returns

The sample in the ticks' unit, or null.

Charting.ChartChrome

The band, the axes and the frame every chart draws for itself.
One place owns the geometry, so the three renderers cannot disagree about where the plot starts, how a legend is laid out, or what an empty chart still shows. The layout is deliberately arithmetic rather than measured: the estimate is a fixed width per character, a row wraps when it would leave the drawing, and a test can pin the result.

FieldTitleHeight

The height the title band takes.

FieldLegendRowHeight

The height of one legend row.

FieldFontSize

The size of the axis and legend labels: the site's body size, one rem.

FieldTitleFontSize

The size of the title: the same size as the labels, set apart by weight rather than height.

FieldSeriesFontSize

The size of the label at the end of a series' line, the same as every other label.

FieldLeftMargin

Where every plot starts. The title and the first legend entry line up with it, so the drawing reads as one column rather than a label band beside a chart.

FieldRightMargin

How much room the right edge keeps clear of the drawing.

FieldBottomMargin

How much room the time labels take below the plot.

MethodBegin(StringBuilder svg, Charting.ChartSize size, string cssClass, Charting.ChartFrame frame, string description)

Writes the opening element, the names and the visible title, and returns the band's foot.

Parameters

svg
The drawing being written.
size
The full drawing area.
cssClass
The drawing's class: chart, heatmap or stacked.
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)

Lays out a legend band and returns the plot's top.

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)

Writes the band and its legend, and works out the plot they leave.

Parameters

svg
The drawing being written.
size
The full drawing area.
cssClass
The drawing's class: chart, heatmap or stacked.
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

Where the plot goes.

MethodPlot(Charting.ChartSize size, double top)

Works out where a plot goes below a band.

Parameters

size
The full drawing area.
top
Where the band ends and the plot may start.

Returns

The plot's rectangle.

Exceptions

ArgumentOutOfRangeException
The size leaves no room to plot in.

MethodWriteLegendItem(StringBuilder svg, Charting.LegendEntry entry, string label)

Writes one legend entry: the series' dash sample and its label.
The caller writes this inside the series' own anchor, so hovering or clicking the legend entry has the same effect as hovering or clicking the line it names.

Parameters

svg
The drawing being written.
entry
Where the entry goes.
label
The series label.

MethodWriteAxisTitle(StringBuilder svg, string title, Charting.ChartPlot plot)

Writes the value axis title, rotated, beside the 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)

Writes the horizontal grid: one line and one value label per tick.

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)

Writes the vertical grid: one line and one time label per tick.

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)

Writes the time labels without the lines, for a plot whose cells are the grid.

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)

Opens one series' anchor, with its hover name and its legend entry.
The caller writes the line or the band inside this anchor and closes it with EndSeries, so hovering or clicking the legend entry does what hovering or clicking the mark does.

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)

Closes the anchor BeginSeries opened.

Parameters

svg
The drawing being written.

MethodEmpty(StringBuilder svg, Charting.ChartPlot plot, string message)

Writes the empty state over a plot that is already gridded and framed.

Parameters

svg
The drawing being written.
plot
The plot that has no data.
message
What to say.

MethodBorder(StringBuilder svg, Charting.ChartPlot plot)

Draws the plot's border: the axes at the edges of the drawn area.
Drawn after the grid and before the series, so it is a frame rather than a line across the data.

Parameters

svg
The drawing being written.
plot
The plot to frame.

MethodDescribe(Charting.ChartTimeAxis x, Charting.ChartAxis y)

Describes a time series for the drawing's desc.

Parameters

x
The time axis.
y
The value axis.

MethodInstant(DateTimeOffset at, TimeZoneInfo zone, TimeSpan span)

Formats an instant for the hover text, in the frame's zone.

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

Cuts the marks a chart draws to the plot it draws them in.
A sample outside the window is cut at the edge rather than pinned to it: a line that stops where the data stops says the data stopped, where a line running along the edge says the value did something it did not. A cut segment keeps its direction, so where it crosses the edge is interpolated from the two samples either side of it.

MethodLine(IReadOnlyList<ValueTuple<double, double>> line, Charting.ChartPlot plot)

The part of a line that falls inside the plot.

Parameters

line
The line's points, in drawing order.
plot
The plot to cut it to.

Returns

The visible points, with the ends of a cut segment interpolated.

MethodStack(IReadOnlyList<ValueTuple<double, double, double>> columns, Charting.ChartPlot plot)

The part of a stack of columns that falls inside the plot.

Parameters

columns
Each column's position and the two values that bound the band.
plot
The plot to cut them to.

Returns

The visible columns, with the ends of a cut segment interpolated.

Charting.ChartFrame

What a chart says about itself: its title, its value axis and its words for no data.
The frame is data, not chrome: every renderer draws the same title band from it, so a chart served on its own has everything it needs and needs no stylesheet to say what it shows.

MethodChartFrame(string Id, string Title, string YTitle, string EmptyText, TimeZoneInfo Zone, string TitleHref)

What a chart says about itself: its title, its value axis and its words for no data.
The frame is data, not chrome: every renderer draws the same title band from it, so a chart served on its own has everything it needs and needs no stylesheet to say what it shows.

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

The fragment prefix for the series anchors; it is unique within one document.

PropertyTitle

The drawing's title, for its accessible name and its title band.

PropertyYTitle

What the value axis measures.

PropertyEmptyText

What to draw when there is nothing to draw.

PropertyZone

The zone the time labels and the hover text are written in.

PropertyTitleHref

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.

PropertyDescription

A sentence explaining what the chart shows, shown when the title is hovered and read by assistive technology. Null falls back to the axis summary the renderer generates.

MethodValidate()

Checks the frame before a renderer draws it.

Exceptions

ArgumentException
The id or the title is blank.

Charting.ChartPlot

The rectangle a chart draws its data in, below the band and above the time labels.

MethodChartPlot(double Left, double Top, double Width, double Height)

The rectangle a chart draws its data in, below the band and above the time labels.

Parameters

Left
The value axis.
Top
The plot's upper edge.
Width
How wide the plot is.
Height
How tall the plot is.

PropertyLeft

The value axis.

PropertyTop

The plot's upper edge.

PropertyWidth

How wide the plot is.

PropertyHeight

How tall the plot is.

PropertyRight

The plot's right edge.

PropertyBottom

The plot's lower edge.

MethodTime(Charting.ChartTimeAxis axis, double seconds)

Where a time sits horizontally: its fraction of the window the axis covers.

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)

Where a value sits vertically: the higher the value, the higher the point.

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

One sample in a chart series.

MethodChartPoint(DateTimeOffset At, double? Value)

One sample in a chart series.

Parameters

At
When the sample was taken.
Value
The value, or null for a gap — Prometheus reports gaps as NaN.

PropertyAt

When the sample was taken.

PropertyValue

The value, or null for a gap — Prometheus reports gaps as NaN.

Charting.ChartSamples

The range arithmetic the charts share.

MethodWiden(double min, double max)

Widens a flat range so a line does not sit on the axis.

Parameters

min
The lowest value.
max
The highest value, equal to min.

Charting.ChartSeries

A named line on a chart.

MethodChartSeries(string Label, IReadOnlyList<Charting.ChartPoint> Points)

A named line on a chart.

Parameters

Label
The legend text; it is escaped where it is drawn.
Points
The samples, ordered by instant.

PropertyLabel

The legend text; it is escaped where it is drawn.

PropertyPoints

The samples, ordered by instant.

Charting.ChartSize

The drawing area of a chart, in SVG user units.

MethodChartSize(double Width, double Height)

The drawing area of a chart, in SVG user units.

Parameters

Width
The full width, including the space the labels need.
Height
The full height, including the space the labels need.

PropertyWidth

The full width, including the space the labels need.

PropertyHeight

The full height, including the space the labels need.

PropertyPlotWidth

The width of the plot itself, which is what a tick label has room to use.

Charting.ChartTick

A labelled position on an axis.

MethodChartTick(double Position, string Label)

A labelled position on an axis.

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

The value the tick marks: seconds after the window's start on a time axis, the sample value itself on a value axis.

PropertyLabel

The text to draw; it is escaped where it is drawn.

Charting.ChartTimeAxis

A chart's time axis: the window it covers, and the ticks drawn along it.
The window is part of the axis rather than something a chart infers from its samples, so the grid, the marks and the labels are all measured from one origin. A sample sits at its fraction of the window, which is what puts a line whose data starts late — or stops early — where it belongs instead of at the plot's left edge.

MethodChartTimeAxis(string Title, DateTimeOffset From, DateTimeOffset To, IReadOnlyList<Charting.ChartTick> Ticks)

A chart's time axis: the window it covers, and the ticks drawn along it.
The window is part of the axis rather than something a chart infers from its samples, so the grid, the marks and the labels are all measured from one origin. A sample sits at its fraction of the window, which is what puts a line whose data starts late — or stops early — where it belongs instead of at the plot's left edge.

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

What the axis measures, for the chart's description.

PropertyFrom

The instant at the axis' left edge.

PropertyTo

The instant at its right edge.

PropertyTicks

The ticks, positioned in seconds after From.

MethodOffset(DateTimeOffset at)

How far an instant is into the window, in seconds after its start.

Parameters

at
The instant to place.

PropertySpan

The window's width in seconds, floored at one so a zero-width window cannot divide by zero.

PropertyDuration

How far the window reaches.

Charting.Heatmap

Turns cumulative histogram counters into a 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

The most columns one heatmap draws.
A distribution over time does not need one column per scrape: sixty columns still show the shape of a day and keep sixteen heatmaps inside the page's markup budget.

MethodFromCumulative(IReadOnlyList<Charting.HeatmapRow> cumulative)

Converts cumulative series into per-bucket values.

Parameters

cumulative
The le series, in any order.

Returns

Rows sorted by boundary with +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)

Renders the heatmap as SVG.

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

One <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)

Folds an answer into at most cap columns, summing each block.
A folded column keeps the instant its block starts at, so it is drawn where the block was.

Parameters

rows
The differenced rows.
cap
The most columns to draw.

Charting.HeatmapRow

One row of a heatmap: a bucket label and its samples.

MethodHeatmapRow(string Label, IReadOnlyList<Charting.ChartPoint> Points)

One row of a heatmap: a bucket label and its samples.

Parameters

Label
The bucket boundary, for example 0.05 or +Inf.
Points
The samples; a null value is a gap.

PropertyLabel

The bucket boundary, for example 0.05 or +Inf.

PropertyPoints

The samples; a null value is a gap.

Charting.LegendEntry

Where one legend entry sits.

MethodLegendEntry(int Index, double X, double Y)

Where one legend entry sits.

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

The series position, which decides the colour and the dash.

PropertyX

The left edge of the key sample.

PropertyY

The top of the entry.

Charting.LineChart

Draws line charts as SVG.

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)

Renders one chart.

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

One <svg> element, with every label escaped.

Exceptions

ArgumentNullException
A required argument is null.
ArgumentOutOfRangeException
The size leaves no room to plot in.

Charting.NiceTicks

Picks readable ticks for a chart axis.

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)

Chooses time ticks between two instants, labelled in a zone.

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.TargetTicks labels.

Returns

The ticks, positioned in seconds after from. A span with no width yields a single tick rather than none.

MethodForValue(double min, double max)

Chooses value ticks for a range.

Parameters

min
The lowest value on the chart.
max
The highest value on the chart.

Returns

Ticks at 1/2/5 × 10ⁿ intervals. A flat range is widened so the line does not sit on the axis, and a range that is not a number yields 0..1.

Charting.StackedAreaChart

Draws a stacked area chart as SVG.

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)

Renders one stacked area chart.

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

One <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

Formatting, escaping and palette values for the markup the charts generate.

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

How many series colours the palette defines.

FieldHeatLevels

How many shades a heatmap uses.

FieldFontFamily

The font stack the site sets on its body, written on every drawing so it reads the same on its own.

FieldTypeScale

How much larger every chart's type is than the first draft's eleven-pixel labels.
The first draft measured its spacing for eleven-pixel labels; the drawings now carry the same sixteen-pixel body type as the page around them, so every distance that holds a label grows by the same ratio. The type grows into its room instead of into its neighbours.

FieldCharacterWidth

Roughly how wide one character is at the labels' size, for laying out a legend.

MethodEscape(string value)

Encodes text for an element body or an attribute value.

Parameters

value
The text, which may be null.

MethodNumber(double value)

Formats a coordinate or a value for an attribute, in the invariant culture.

Parameters

value
The number to write.

MethodSeriesColour(int index)

The CSS class for the nth series, cycling through the colours the palette defines.

Parameters

index
The series position, counted from zero.

MethodSeriesStroke(int index)

The stroke for the nth series.

Parameters

index
The series position, counted from zero.

MethodSeriesDash(int index)

The dash pattern for the nth series, or null for a solid line.

Parameters

index
The series position, counted from zero.

MethodHeatFill(int level)

The fill for a heatmap level, from 1 (palest) to 5 (darkest).

Parameters

level
The level, clamped to the palette's range.

MethodEstimateWidth(string text)

Estimates the width of a label, for wrapping a legend without measuring text.

Parameters

text
The label.

Compilation

Compilation.ApiReference

One API a page referenced, as plain data.
The runtime projects Roslyn symbols onto these values, so the policy itself stays a pure function over strings and never sees a compiler type.

MethodApiReference(string Namespace, string Type, string Member, Compilation.TemplatePosition? Position)

One API a page referenced, as plain data.
The runtime projects Roslyn symbols onto these values, so the policy itself stays a pure function over strings and never sees a compiler type.

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

The namespace the API lives in, for example System.IO.

PropertyType

The type name without its namespace, for example File.

PropertyMember

The member used, or string.Empty for a plain type reference.

PropertyPosition

Where the reference appears in template space, or null when it is generated code.

Compilation.GeneratedSource

The generated C# source of a page's handler: the form between a template and an assembly.

MethodGeneratedSource(string text)

Wraps generated source.

Parameters

text
The C# the template generator produced.

Exceptions

ArgumentException
The text is empty.

PropertyText

The generated C# source, ready for the compiler.

Compilation.PageApiPolicy

What page code is allowed to name.

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)

Reports every reference the policy does not allow.

Parameters

used
The APIs the page referenced, in the order they appear.

Returns

One diagnostic per refused type, naming the member or the type the page referenced and its template position; empty when the page is within the policy.

Compilation.PageDiagnostic

One problem found in a page, ready to display.

MethodPageDiagnostic(Compilation.PageDiagnosticSeverity Severity, Compilation.TemplatePosition? Position, string Message)

One problem found in a page, ready to display.

Parameters

Severity
Whether the page can still run.
Position
Where in the template, or null when the position is not known.
Message
The diagnostic code and text, without severity or position.

PropertySeverity

Whether the page can still run.

PropertyPosition

Where in the template, or null when the position is not known.

PropertyMessage

The diagnostic code and text, without severity or position.

PropertySource

The key of the page the diagnostic belongs to, or null for the page being compiled. A library compiled into a page contributes its diagnostics under its own key.

MethodSortedForDisplay(IEnumerable<Compilation.PageDiagnostic> diagnostics)

Orders diagnostics the way the author reads them: the page first, then its libraries.
The page's own diagnostics come first, then each library's by key, and within one source a diagnostic without a position sorts last. The sort is stable, so diagnostics at the same position keep the order the compiler gave them.

Parameters

diagnostics
The diagnostics to order.

Returns

The same diagnostics, ordered for display.

MethodToString()

Renders the diagnostic as one line, with its position and severity.

Compilation.PageDiagnosticSeverity

How serious a Compilation.PageDiagnostic is.

FieldWarning

The page runs; the author is told and the image is kept.

FieldError

The page cannot run; no image is emitted.

Compilation.ScriptSkeletonResult

A page's literal text, with template constructs replaced so a JavaScript parser can read it without changing any position.

MethodScriptSkeletonResult(string Source, IReadOnlyList<Compilation.PageDiagnostic> Diagnostics)

A page's literal text, with template constructs replaced so a JavaScript parser can read it without changing any position.

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

The template's text with every template construct blanked, or an empty string when the template could not be tokenized.

PropertyDiagnostics

The tokenizer's errors, already positioned in template space; empty when a skeleton was produced.

PropertyIsSuccess

Whether the template was tokenized and a skeleton produced.

Compilation.TemplateComments

The literal text of a template: its source with every comment construct removed.

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)

Removes every comment construct from a template.

Parameters

template
The template as its author wrote it.

Returns

The template's text with each <%# … %> 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

Identifies one version of a page's template by its text.

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)

Fingerprints a page template.

Parameters

template
The template source.

Returns

The lowercase hexadecimal SHA-256 of the template's UTF-8 bytes.

Compilation.TemplateGenerationResult

The outcome of generating handler source from a page template.

MethodTemplateGenerationResult(Compilation.GeneratedSource Source, IReadOnlyList<Compilation.PageDiagnostic> Errors)

The outcome of generating handler source from a page template.

Parameters

Source
The generated source, or null when the template did not parse.
Errors
The problems that stopped generation, already positioned in template space; empty when Source was generated.

PropertySource

The generated source, or null when the template did not parse.

PropertyErrors

The problems that stopped generation, already positioned in template space; empty when Source was generated.

PropertyKind

What the template is for, judged from its tokens.

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

Template line-and-column arithmetic shared by the tokenizer, the generator and the editor gutter.
\r\n, \n and a lone \r are line breaks; other Unicode separators are not. Keeping the rule here means the tokenizer's positions, the generated #line mapping and the editor's line numbers cannot disagree.

MethodCount(string input)

The number of lines in a template.

Parameters

input
The template source.

Returns

The line count, which is at least one: an empty template is one empty line.

MethodPositionOf(string, int)

The template position of a 0-based offset.

MethodAdvance(Compilation.TemplatePosition position, string text)

Advances a template position over a piece of template text.

Parameters

position
The position before the text.
text
The text to move past.

Returns

The position immediately after the text.

Compilation.TemplatePosition

A 1-based line and column in the page template, as the author typed it.
The only coordinate system that is stored or displayed. Generated-source coordinates stay inside Roslyn; an unknown position is null, never (0, 0), so it cannot be mistaken for a real one.

MethodTemplatePosition(int Line, int Column)

A 1-based line and column in the page template, as the author typed it.
The only coordinate system that is stored or displayed. Generated-source coordinates stay inside Roslyn; an unknown position is 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

The 1-based line in the template.

PropertyColumn

The 1-based column in the template.

MethodToString()

Inherited from object.ToString.

Compilation.TemplateScriptSkeleton

Turns a page template into the literal JavaScript a parser can read, without rendering it.
A script page is still a template: the JavaScript is the text a browser would have received if no template construct had produced any output. The skeleton keeps that text exactly where the author typed it, so a parser's line and column are page positions. Code, comment, declaration and write constructs are replaced by spaces — and every line break is kept — rather than removed, so tokens either side of a construct stay separated; a write becomes 0 and spaces so an expression position stays valid.

MethodCreate(string template)

Builds the skeleton of a template.

Parameters

template
The page template as its author wrote it.

Returns

The template's literal text with its constructs blanked, or the tokenizer's TEMPLATE001 errors and an empty source when the template cannot be tokenized.

Compilation.TemplateShapeCheck

Finds template-shape problems that compile cleanly and quietly change the page.
The C# compiler sees generated code, so a missing %> 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)

Checks a template for stray closers and unbalanced braces in page code.

Parameters

template
The template as its author wrote it.

Returns

The warnings, ordered by template position; empty when the shape looks sound.

Compilation.TemplateSourceGenerator

Turns a page template into the generated C# source of its handler.

MethodGenerate(string template)

Generates the handler source for a page template.

Parameters

template
The page template.

Returns

The generated source, or the errors and no source when the template does not parse. No partial source is generated for a template that does not parse: Roslyn would then report a syntax error where the text was cut off on top of the real one, and the author would fix the wrong thing.

MethodGenerateLibrary(string template)

Generates the unit a library contributes: its declarations, and no handler.

Parameters

template
The library template.

Returns

The declarations, each mapped to the line and column the author wrote.

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

The template language: text, C# blocks, comments, declaration blocks, and escaped or raw value writes.

MethodTokenize(string input)

Splits a page template into text, code, comment, declaration and write tokens.

Parameters

input
The template as its author wrote it.

Returns

The tokens, and one error naming the opener of an unterminated block.

Compilation.Token

A piece of a page template: text, code, a comment, declarations, or an escaped or raw write.

MethodToken(Compilation.TokenType Type, string Value, Compilation.TemplatePosition Position, Compilation.TemplatePosition? OpenerPosition)

A piece of a page template: text, code, a comment, declarations, or an escaped or raw write.

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 null otherwise.

PropertyType

What kind of content the token contains.

PropertyValue

The token's content, without its delimiters.

PropertyPosition

Where the content starts, in template space.

PropertyOpenerPosition

Where a write token's opener starts, or null otherwise.

Compilation.TokenType

What a Compilation.Token contains.

Compilation.TokenizeResult

The tokens a template yields, and the problems that stopped tokenization.
A malformed template is input rather than a fault, so it is reported as a value. That is what lets a page that does not parse fail the same way as a page that does not compile: stored with its diagnostics, and shown to the author in the editor.

MethodTokenizeResult(IReadOnlyList<Compilation.Token> Tokens, IReadOnlyList<Compilation.PageDiagnostic> Errors)

The tokens a template yields, and the problems that stopped tokenization.
A malformed template is input rather than a fault, so it is reported as a value. That is what lets a page that does not parse fail the same way as a page that does not compile: stored with its diagnostics, and shown to the author in the editor.

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

Every token taken from the template before tokenization stopped.

PropertyErrors

The problems found, already positioned in template space; empty when the whole template was tokenized.

PropertyIsSuccess

Whether the whole template was tokenized.

Diff

Diff.DiffDocument

The line changes between two documents.

MethodDiffDocument(IReadOnlyList<Diff.DiffHunk> Hunks, int AddedLines, int RemovedLines, bool IsCoarse)

The line changes between two documents.

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

The changed regions, in document order; empty when the documents have the same lines.

PropertyAddedLines

How many lines the later document adds.

PropertyRemovedLines

How many lines the later document removes.

PropertyIsCoarse

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.

PropertyIsEmpty

Whether the two documents have the same lines.

Diff.DiffHunk

A contiguous group of changed lines and their context.

MethodDiffHunk(int BeforeStart, int BeforeCount, int AfterStart, int AfterCount, IReadOnlyList<Diff.DiffLine> Lines)

A contiguous group of changed lines and their context.

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

The first before line number the hunk covers, or the line it follows when it covers none.

PropertyBeforeCount

How many lines the hunk covers in the earlier document.

PropertyAfterStart

The first after line number the hunk covers, or the line it follows when it covers none.

PropertyAfterCount

How many lines the hunk covers in the later document.

PropertyLines

The hunk's context, removed and added lines, in document order.

Diff.DiffLine

One line of a diff, with the line numbers it has in each document.

MethodDiffLine(Diff.DiffLineKind Kind, string Text, int? BeforeLine, int? AfterLine)

One line of a diff, with the line numbers it has in each document.

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

Whether the line is context, added or removed.

PropertyText

The line's text, without its terminator.

PropertyBeforeLine

The 1-based line number in the earlier document, or null for an added line.

PropertyAfterLine

The 1-based line number in the later document, or null for a removed line.

Diff.DiffLineKind

What one line of a diff represents.

FieldContext

The line is in both documents.

FieldAdded

The line is only in the later document.

FieldRemoved

The line is only in the earlier document.

Diff.LineDiff

Compares two documents line by line.

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

How many unchanged lines surround each changed region.

FieldMaxEditDistance

How many edits the algorithm may find before it gives up on alignment.

FieldMaxLines

How many differing lines a document pair may have before the algorithm gives up on alignment.

MethodCompare(string before, string after)

Compares two documents line by line.

Parameters

before
The earlier document.
after
The later document.

Returns

The changes, grouped into hunks with ContextLines lines of context.

Exceptions

ArgumentNullException
Either document is null.

MethodCompare(string before, string after, int contextLines, bool ignoreSpaceChange)

Compares two documents line by line, with as much context as asked for.
The ignored difference is the whitespace, never the line: the comparison runs on a collapsed copy of each line and the text in the result is put back as it was written.

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 -b means it to.

Returns

The changes, grouped into hunks with contextLines lines of context.

Exceptions

ArgumentNullException
Either document is null.
ArgumentOutOfRangeException
contextLines is negative.

MethodAsWritten(Diff.DiffDocument, string[], string[])

The comparison's alignment, with each line's text put back as it was written.

Diff.NormalDiff

Writes a Diff.DiffDocument in the normal format, which is the default one.
One line per change block — 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)

Writes the normal-format diff text.

Parameters

diff
The comparison to write.

Returns

The change blocks, or the empty string when nothing changed.

Exceptions

ArgumentNullException
diff is null.

Diff.UnifiedDiff

Writes a Diff.DiffDocument as unified diff text.

MethodToUnified(Diff.DiffDocument diff)

Writes the canonical unified diff text.

Parameters

diff
The comparison to write.

Returns

One @@ -a,b +c,d @@ header per hunk followed by lines prefixed with a space, - or +, or the empty string when nothing changed.

Exceptions

ArgumentNullException
diff is null.

Markdown

Markdown.LinkPolicy

Which URLs the restricted Markdown renderer may turn into a link.

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)

Returns whether a restricted renderer may make 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

What a page key's extension names: its media type and its script policy.

MethodPageContentTypeRule(string MediaType, Pages.PageScriptPolicy ScriptPolicy)

What a page key's extension names: its media type and its script policy.

Parameters

MediaType
The response content type, including any parameters.
ScriptPolicy
The response's script policy; None by default.

PropertyMediaType

The response content type, including any parameters.

PropertyScriptPolicy

The response's script policy; None by default.

Pages.PageContentTypes

Which media type and script policy each page key gets, and the fallback for the rest.

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

What a key with no mapped extension gets.

PropertyFallbackRule

The whole fallback rule, including its script policy.

PropertyExtensionCount

How many extensions are mapped.

MethodCreate(string fallback, IEnumerable<KeyValuePair<string, string>> extensions)

Builds a map from a fallback media type and one media type per extension.

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

The map to use.

Exceptions

ArgumentException
The fallback, a key or a media type is invalid.

MethodCreate(Pages.PageContentTypeRule fallback, IEnumerable<KeyValuePair<string, Pages.PageContentTypeRule>> extensions)

Builds a map from a fallback rule and one rule per extension.

Parameters

fallback
The rule for a key with no mapped extension.
extensions
Extension rows, keyed by the extension including its dot.

Returns

The map to use.

Exceptions

ArgumentException
The fallback, a key, a media type or a script policy is invalid.

MethodRuleFor(string path)

The rule a page's key names.

Parameters

path
A page key or raw request path.

Returns

The mapped rule, or FallbackRule when the last segment has no mapped extension.

MethodForPath(string path)

The response type a page's key names.

Parameters

path
A page key or raw request path.

Returns

The mapped media type, or Fallback when the last segment has no mapped extension.

MethodScriptsForPath(string path)

The script policy a page's key names.

Parameters

path
A page key or raw request path.

Returns

The mapped policy, or the fallback's when the last segment has no mapped extension.

Pages.PageGlob

Matches page keys against the pattern language a shell expands a path with.

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)

Whether a key matches a pattern written as a plain string.

Parameters

pattern
The pattern, as a path a shell would expand.
key
A canonical page key.

MethodIsMatch(Shell.ShellWord pattern, string key)

Whether a key matches a word, which knows which of its characters were quoted.

Parameters

pattern
The word, as the caller wrote it.
key
A canonical page key.

Pages.PageKind

What a stored template is for, decided by its source rather than its key.

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

No C# at all, so its source, less its comments, is the response.

FieldPage

C# that renders: it is compiled to a handler and wrapped in the site layout.

FieldLibrary

Only declarations: compiled into the pages that name it, and never served.

FieldWorker

Declarations that declare one entry point: started by a page, and never served.

Pages.PageMode

The permission column a long listing prints, answered in one place.
There is no host file mode here: -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)

The mode of a page or shell file.

Parameters

canWrite
Whether a save would be accepted.

MethodDescribeFolder(bool canWrite)

The mode of a folder.

Parameters

canWrite
Whether a save below it would be accepted.

Pages.PagePath

A canonical key for a stored page: an absolute, lowercase, slash-separated path.

Normalize applies these steps in order:

  1. A null, empty or whitespace-only path is the root, /.
  2. The text is lowercased with the invariant culture, so /Hello and /hello are the same key.
  3. The text is composed to Unicode NFC, so a precomposed accent and a combining accent give the same key.
  4. The text is split on / and empty segments are dropped, so leading, trailing and repeated slashes collapse: //hello// becomes /hello.
  5. . segments are dropped.
  6. .. removes the preceding segment, or is dropped when there is nothing left to remove: /a/../b becomes /b, and /.. becomes /.
  7. 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

The canonical key: absolute, lowercase, and never ending with / unless it is the root.

PropertyIsAddressable

Whether the key can name a page a request may be served from.
The only way to get a false is a request that encoded a delimiter, such as /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)

Normalises text into the canonical key for the page it names.
The steps are listed on Pages.PagePath.

Parameters

path
The text to normalise, typically a path route value.

Returns

The canonical key, which is / when path is null, empty or whitespace.

MethodToString()

The page key, as the site spells it.

Pages.PageQueryFingerprint

A stable fingerprint of a query, for telling one render of a page from another.

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)

Fingerprints a query, in the order its names and values arrived.

Parameters

query
Every query value, per name, in order.

Returns

A string that is equal for the same query and different for a different one.

Exceptions

ArgumentNullException
query is null.

Pages.PageScope

One question a search asks of the tree: which keys it may read.
A path names a page as readily as a folder, so a search usually includes it; it is left out when a caller wants to read a folder's entries and not the folder's own key. The root is special only in that everything but the root is below it.

MethodPageScope(Pages.PagePath Path, bool IncludeSelf, bool Recursive)

One question a search asks of the tree: which keys it may read.
A path names a page as readily as a folder, so a search usually includes it; it is left out when a caller wants to read a folder's entries and not the folder's own key. The root is special only in that everything but the root is below it.

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

The path the search starts at.

PropertyIncludeSelf

Whether the path itself is read, as well as what is below it.

PropertyRecursive

Whether everything below the path is read, or only what is directly below.

MethodContains(Pages.PagePath key)

Whether a key is inside this scope.

Parameters

key
The key to test.

Pages.PageScriptPolicy

The script policy a page key's extension gives its response.
The policy follows the key's extension, not the response's final content type: a page that calls 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

No script may load.

FieldSelf

A same-origin external script may load.

Pages.PageSourceChange

The one test a write that names its source asks: would it change anything?

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)

Whether storing a source would leave the page's source as it is.

Parameters

live
The live source, or null when 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

The page store's keys as the tree they form.
A key is a path, so the store is a tree and "below", "directly below" and "the folder above" are one rule each. The assistant's tools and its virtual shell both read the store and both speak of it as a tree, so the rule lives here rather than in either of them.

MethodIsBelow(Pages.PagePath key, Pages.PagePath folder)

Whether a key lives anywhere below a path.

Parameters

key
The key to test.
folder
The path to test it against.

Returns

True for a key under the folder at any depth. A folder is not below itself, and a prefix that is not a whole segment (/ab for /a) is another key. Every key but the root is below the root.

MethodIsDirectlyBelow(Pages.PagePath key, Pages.PagePath folder)

Whether a key is an entry of a path: below it, and no deeper than one segment.

Parameters

key
The key to test.
folder
The path to test it against.

MethodFolderOf(string key)

The folder a key lives in, or null when that folder is the root.

Parameters

key
A canonical key.

Returns

The key's parent, or null for a key directly under the root and for the root itself.

MethodFoldersAbove(string key)

Every folder above a key, outermost first.

Parameters

key
A canonical key.

Returns

The folders a listing has to show for the key to be reachable, such as /a and /a/b for /a/b/c. A key directly under the root has none, because the root is always there.

Pages.RevisionHash

Creates stable addresses for individual saved page revisions.

FieldLength

The length of every stored hash: 32 SHA-256 bytes in lowercase hexadecimal.

FieldFormatVersion

The versioned framing prefix used by the revision identity format.

MethodIsCanonical(string hash)

Whether a value is exactly the lowercase hexadecimal hash storage writes.

Parameters

hash
The value to test.

Returns

True only for 64 lowercase hexadecimal characters. Case folding, truncation and padding are all refused, so a URL that names a revision has one spelling and one ordinal comparison.

MethodOf(string source, string creationRuntimeId, DateTimeOffset savedAt, string revisionId)

Hashes the source and immutable identity fields for a saved revision.

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

A lowercase 64-character SHA-256 digest.

Pages.SeedComparison

The three-value comparison, and the two writes it permits.

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)

The three-value comparison, and the two writes it permits.

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

What the row is, relative to the seed.

PropertyCanApply

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.

PropertyCanAdopt

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.

MethodOf(string recorded, string shipped, string content)

Compares a page's recorded anchor, the shipped seed and the live content.

Parameters

recorded
R, or null when the page has no record of a seed.
shipped
S, or null when the release ships no seed for the key.
content
H, or null when the page has no live content.

Returns

The verdict, and whether the row may be applied or adopted.

Pages.SeedVerdict

What a page's stored content is, relative to the seed the release ships.

FieldInSync

The page holds exactly the seed this release ships.

FieldReleaseNewer

The release moved the seed, and the page still holds the one it was installed from.

FieldEdited

The page changed after its seed set it, and the seed itself did not move.

FieldConflict

The page changed after its seed set it, and the release moved the seed too.

FieldStoreNewer

The page holds the shipped bytes but is not recorded as installed from them.

FieldUnknown

The page has no record of coming from a seed.

FieldRetired

The release no longer ships a page at this key.

Shell

Shell.ShellArgument

One operand as the line gave it, with the kind the command declared for it.

MethodShellArgument(Shell.ShellOperandKind Kind, Shell.ShellWord Word)

One operand as the line gave it, with the kind the command declared for it.

Parameters

Kind
How the command reads it.
Word
The word itself, quoting and all.

PropertyKind

How the command reads it.

PropertyWord

The word itself, quoting and all.

Shell.ShellCommandLine

A command's command line: the flags and values it was given, and its operands.

MethodShellCommandLine(IReadOnlySet<char> Flags, IReadOnlyDictionary<char, string> Values, IReadOnlyList<Shell.ShellArgument> Arguments, IReadOnlyList<Shell.ShellWord> Trailing)

A command's command line: the flags and values it was given, and its operands.

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

The flags, as the letters that were written.

PropertyValues

The value options, as the text each was given.

PropertyArguments

The operands, in the order they were written, each with its declared kind.

PropertyTrailing

The words the command's own grammar owns, when its syntax allows them.

MethodHas(char flag)

Whether a flag was given.

Parameters

flag
The letter after the dash.

MethodValue(char letter)

The text a value option was given, or null when it was not given.

Parameters

letter
The letter after the dash.

MethodNumber(char letter)

The number a value option was given, or null when it was not given or is not a number.

Parameters

letter
The letter after the dash.

MethodWords(Shell.ShellOperandKind kind)

The operands of one kind, in the order they were written.

Parameters

kind
The kind to take.

Shell.ShellLexResult

A lexed command line, or the fault that stopped it.

MethodShellLexResult(IReadOnlyList<Shell.ShellToken> Tokens, string Error)

A lexed command line, or the fault that stopped it.

Parameters

Tokens
The words and operators, in the order they were written.
Error
A safe message, or null when the line lexed.

PropertyTokens

The words and operators, in the order they were written.

PropertyError

A safe message, or null when the line lexed.

PropertyWords

The words of the line, without its operators.

PropertyOperator

The first operator the line carries, when it carries one.

Shell.ShellLine

Splits a command line into words and operators.

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)

Splits a command line into words and operators.

Parameters

text
The line as the caller wrote it.

MethodExpansionError(char)

Why an unquoted $ or backtick stops the line.

Shell.ShellMatchResult

A command line that matched its command's syntax, or the refusal that says it did not.

MethodShellMatchResult(Shell.ShellCommandLine Line, string Error)

A command line that matched its command's syntax, or the refusal that says it did not.

Parameters

Line
What was matched, or null when the line was refused.
Error
A safe message, or null when the line matched.

PropertyLine

What was matched, or null when the line was refused.

PropertyError

A safe message, or null when the line matched.

Shell.ShellOperand

One operand a command takes, and how many of it.

MethodShellOperand(string Name, Shell.ShellOperandKind Kind, int Minimum, int Maximum)

One operand a command takes, and how many of it.

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

What the operand is called in a usage line.

PropertyKind

How the command reads it.

PropertyMinimum

How many are required.

PropertyMaximum

How many are accepted.

Shell.ShellOperandKind

What a command reads an operand as.

FieldText

A word the command reads as text: grep's query.

FieldPath

A path that must name a page: cat's file.

FieldPrefix

A path that may name a folder, or a pattern: ls's directory.

Shell.ShellOperator

An operator between commands.
The lexer reports an operator; it does not judge it. Whether a line with one is refused, and which commands may appear on either side, is the kernel's decision, so that adding pipelines is a change to the kernel and not to the way a line is read.

MethodShellOperator(char Character)

An operator between commands.
The lexer reports an operator; it does not judge it. Whether a line with one is refused, and which commands may appear on either side, is the kernel's decision, so that adding pipelines is a change to the kernel and not to the way a line is read.

Parameters

Character
The character: |, >, <, &, ;, or a line break.

PropertyCharacter

The character: |, >, <, &, ;, or a line break.

Shell.ShellSegment

One run of a word's characters, and whether the line made them literal.

MethodShellSegment(string Text, bool IsLiteral)

One run of a word's characters, and whether the line made them literal.

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

The characters, with the quote or backslash that made them literal removed.

PropertyIsLiteral

Whether a quote or an escape stood in front of them, so that a wildcard among them is the character and not a pattern.

Shell.ShellSyntax

What a command accepts on its command line.
A command declares its flags, its value options and its operands once, and Match is the only thing that turns a line into them: flags may cluster (-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)

What a command accepts on its command line.
A command declares its flags, its value options and its operands once, and Match is the only thing that turns a line into them: flags may cluster (-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

The letters that are flags.

PropertyValues

The letters that take a number.

PropertyOperands

The operands, in the order they are written.

PropertyTrailing

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.

PropertyNothing

A command that takes nothing.

MethodMatch(IReadOnlyList<Shell.ShellWord> words, string usage)

Matches a command line against this syntax.

Parameters

words
The words of the line, after the command's name.
usage
The command's usage line, quoted in a refusal.

Shell.ShellToken

One token of a command line.
Closed: a line holds words and operators, and nothing outside this assembly may add a third token kind, so a matcher can rely on the set.

Shell.ShellValueOption

An option that takes a value, written -n 5, -n5 or -name pattern.

MethodShellValueOption(char Letter, string Name, bool Numeric)

An option that takes a value, written -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

The letter after the dash.

PropertyName

What the value is, in the wording a refusal uses: "a number", "a pattern".

PropertyNumeric

Whether the value has to be a number.

Shell.ShellWord

A word: its characters, and which of them the line made literal.

MethodShellWord(IReadOnlyList<Shell.ShellSegment> Segments)

A word: its characters, and which of them the line made literal.

Parameters

Segments
The word's runs of characters, in the order they were written.

PropertySegments

The word's runs of characters, in the order they were written.

PropertyText

The word as text, quoting applied.

PropertyHasWildcard

Whether the word carries an unquoted * or ?.

Text

Text.JsonSerialization

The one escaping policy for every JSON body the site writes.

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

The encoder for every string the site writes as JSON.

PropertyOptions

A template carrying the framework's web defaults and Encoder.

Text.LowercaseText

The canonical form of text whose case a key ignores: lowercased with the invariant culture and composed to Unicode NFC.

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)

Lowercases 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

The canonical lowercase form of value.

Exceptions

ArgumentNullException
value is null.
ArgumentException
value is not valid Unicode.

Text.MessageText

Turns untrusted text into one bounded line fit to be quoted in a message.

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

The longest sanitised value, counting the ellipsis as one text element.

FieldEllipsis

Appended when a value is shortened to MaximumLength.

MethodSanitize(string value)

Sanitises value into one line of at most MaximumLength text elements.

Parameters

value
The untrusted text to quote. It is neither validated nor preserved.

Returns

The printable text, collapsed to one line, with no leading or trailing space.

Exceptions

ArgumentNullException
value is null.