# Osy# — the reference and the specification, as one Markdown file > Generated 2026-09-15 from the same sources as https://osysharp.com. Each page below is at the URL in its heading; its fenced examples declare how they are verified (`test`/`run` are compiled by CI; `syntax` is a fragment; `preview` is a surface not built yet). --- # §1 · Scope, conformance, and notation > **Status: DRAFT.** Claims marked ⚑ were probed against the compiler; the probe is named. Claims marked > **UNVERIFIED** were not, and must not be relied on. ## 1.1 Scope This document specifies the Osy# language: its lexical structure, types, declarations, expressions, and the semantics a conforming implementation must give them. Osy# is unusual in three ways that the specification must cover explicitly, because a reader arriving from C# will assume otherwise: 1. **A program spans two execution sides.** One source unit compiles into code that runs in a browser and code that runs on a server. Which side a member runs on is **inferred** (§6), not declared. 2. **Execution is durable.** A call may suspend and resume in a different process (§9). This is not a library facility; it changes what an expression means, and it is why some C# constructs are refused (§11). 3. **Authorization is part of the language.** Access rules are declared on a type and enforced beneath every read and write (§8). No program text can bypass them. The runtime, the toolchain (`osy …`), the bundled UI kit, and the platform's hosted services are **outside** this scope. They are specified where they change the meaning of a program, and only there. ## 1.2 Conformance A **conforming implementation** accepts every program this specification defines as valid, and rejects every program it defines as invalid, with a diagnostic. ⚠ **Diagnostics are part of the contract, not an implementation detail** (§12). Osy# refuses a great deal on purpose, and a refusal that does not say what to write instead is a defect in the implementation, not a matter of taste. Where this specification defines a refusal it also states what the diagnostic must convey. ## 1.3 What is normative Normative text uses **MUST**, **MUST NOT**, **MAY** in the usual sense. Everything else — rationale, comparisons to C#, notes on why a rule exists — is **informative**. It is kept because for this language the reasons are frequently the useful part, but a conforming implementation is judged only against the normative text. ## 1.4 Notation Grammar is given in a bracketed EBNF: | form | meaning | |---|---| | `x?` | optional | | `x*` | zero or more | | `x+` | one or more | | `x \| y` | alternatives | | `( … )` | grouping | | `'text'` | a literal token | | *italic* | a non-terminal defined elsewhere in this document | ⚠ **The grammar in this document is written FROM the parser, and is not itself the parser.** Where the two disagree the parser is correct and this document has a bug — report it rather than working around it. Sections whose grammar has been checked against a probe say so; sections that have not are marked **UNVERIFIED**. ## 1.5 How claims in this document are established Every normative claim is expected to carry one of: - ⚑ **a probe** — the smallest program that distinguishes the claim, and what `osy validate` answered; - **a test** — a named test class that asserts the behaviour, for anything `validate` cannot see (runtime semantics, durability, security enforcement); - **UNVERIFIED** — stated but not established. Treat as a lead. This is not ceremony. Three documents in this repository were deleted in the month before this specification was started, each for confidently describing surface the language no longer had. The difference between those and this one is meant to be the probe. --- # §2 · Lexical structure > **Status: DRAFT.** The keyword set (§2.3) is probed. Literals and operators are **UNVERIFIED** and marked so. ## 2.1 Source text An Osy# source file is Unicode text with the extension `.osy`. ⚑ **A generated migration is NOT Osy# and does not use this extension.** Migrations are `.migration`, in their own grammar, and are specified in §13. The extension is deliberate: a migration carried the `.osy` extension until 2026-08-26 and was swept up by every `*.osy` glob — including globs outside this project, which is why the fix is an extension and not a filter. ## 2.2 Comments ``` // line comment, to end of line /* block comment */ /// documentation comment, attached to the following declaration ``` Documentation comments are **not** decoration: they are carried into the model and served by `osy docs` and the language server. **UNVERIFIED**: whether a `///` in a position with no following declaration is an error. ## 2.3 Keywords ⭐ **Osy# has a SMALL reserved set and a LARGE contextual vocabulary, and this is the first thing that surprises a reader.** Exactly **22** words are reserved. Every other word that looks like a keyword — `entity`, `component`, `render`, `workflow`, `state`, `event`, `subscribe`, `security`, `allow`, `deny`, `policy`, `terminal`, `live` — is **contextual**: recognised by the grammar at the position where it means something, and an ordinary identifier everywhere else. ### 2.3.1 Reserved words These MUST NOT be used as identifiers: ``` async await break catch continue else false finally foreach if in is new not null return throw true try var void while ``` ⚑ **Probe (established, and RUN BY CI).** A reserved word used as an identifier is refused. Source of the set: the lexer's `Keywords` table, `OsySharpLexer.cs:94`. ```osy probe=refuses PARSE_ERROR int Probe() { var new = 1; return new; } ``` ### 2.3.2 Contextual words A word that introduces a declaration is not reserved, and MAY be used as an identifier. ⚑ **Probe (established, and RUN BY CI).** Every one of these is a declaration keyword somewhere in the grammar, and an ordinary identifier here: ```osy probe=accepts int Probe() { var entity = 1; var component = 2; var render = 3; var state = 4; return entity + component + render + state; } ``` *Informative.* This follows C#, which reserves a fixed set and makes later additions contextual so that adding a word to the language cannot break existing programs. Osy# takes the same position, and takes it further: the words that introduce its most distinctive constructs are all contextual, so a program that used `workflow` as a variable name before workflows existed still compiles. ⚠ **Consequence for tooling, and for readers:** you cannot decide what a word means by looking it up in a list. `state` is a declaration keyword inside a `workflow` body and a variable name in a function body. Syntax highlighting that colours it unconditionally is wrong, and so is a mental model that treats these as reserved. ### 2.3.3 Words that are NOT in the language **UNVERIFIED as a complete list**, but recorded because each has been mistakenly assumed to exist: | assumed | actual | |---|---| | `out`, `ref` | **refused** — a parameter passes a value in, and only the return comes back out. A call can suspend and resume elsewhere, so no caller frame is guaranteed to still be waiting for a write-back. See §11. | | `[Display]` | replaced by `[Label]` | | `Now` | removed entirely; use `DateTime.UtcNow`, which the compiler lowers to the ambient clock | ## 2.4 Identifiers **UNVERIFIED.** Expected to follow C# — a letter or `_` followed by letters, digits or `_`, compared ordinally. The probe that would establish this (a Unicode identifier, a leading digit, `@`-escaping) has not been written. Members are `PascalCase` and parameters `camelCase` by convention; this is style, not grammar, and the linter — not the compiler — enforces it. ## 2.5 Literals **UNVERIFIED.** The forms below are observed in real source but their exact grammar has not been probed: | kind | observed | |---|---| | integer | `1`, `0` | | decimal | `2m` — a suffixed decimal literal | | string | `"…"` and interpolated `$"…{expr}…"` | | boolean | `true`, `false` | | null | `null` | ## 2.6 Operators and punctuation **UNVERIFIED as a complete table.** Two facts are established elsewhere and belong here when this section is written properly: - ⚑ `??` over numeric operands **WIDENS** to the wider type, rather than dropping to the narrower one. The previous rule produced wrong numbers, not merely a dropped cast (fixed 2026-08-26, `f15275418`). - ⚑ `xs[i]` on a collection is **not** a nullable read — the resolver briefly said it was, and a MUST-tier lint believed it (fixed 2026-08-26, `8ed45bfbd`). --- **Next:** §3 Types — the type system, nullability, and the required-by-default rule (R12). Not started. --- # §6 · The execution-side model > **Status: DRAFT.** The side vocabulary and one inference are probed. The *correctness* of inference at runtime, > and what crosses the wire, are **UNVERIFIED here by construction** — see §6.6. This is the language's most distinctive rule, and the one §11.1 and §11.2 both depend on. ## 6.1 One unit, more than one runtime A single compilation unit produces code that runs in a browser and code that runs on a server. There is no wire protocol to declare, no endpoint to route, and no data-transfer type to keep in step, because there is no boundary in the source for those things to sit on. **Normative.** A program MUST NOT be required to state where a member runs. An implementation MUST determine it. ## 6.2 The three sides ⚠ **The model is three-valued, not two.** A reader who assumes "client or server" will mispredict the third and most interesting case. | side | meaning | |---|---| | **Server** | the authority for data **reads**, security, and secrets — the server interpreter runs it | | **Client** | dialogs, local UI, interaction — the client runtime runs it | | **Either** | pure compute **and local data mutation** (`new`, assignment) — runs wherever the cursor already is, and **may span the boundary** | *Source: `ExecutionSide`, `OsySharpExpressionEnums.cs:539`.* ⭐ **`Either` is where the model earns itself.** A pure helper does not need a home, so it does not get one — it runs on whichever side called it, and the same function called from a render slot and from a server function is not two functions. Local mutation is `Either` for the same reason: creating a row or assigning a field acts on the unit of work the cursor already holds, so it is meaningful on both sides and identical on both. ## 6.3 Inference The side follows from **what the code touches**, not from what it is called or where it is written. - an **entity read** materialises rows under the declared row filter (§8) → **Server** - a **render** expression paints and performs no I/O → **Client** - **pure compute** and local mutation → **Either** ⚑ **Probe (established, and run by CI).** A `live var` holding an entity read is reported `side=server`: ```osy probe=accepts using Osysharp.Ui; entity Order { [MaxLength(40)] string Ref; int Total; } [Page("/")] [AllowAnonymous] component Board() { live var orders = Order.Where(o => o.Total > 0); render { foreach (var o in orders) { Text(o.Ref); } } } ``` `osy model --json` reports, for that component member: ``` component Board members: orders side=server ``` ## 6.4 Asking the compiler **Normative.** An implementation MUST make the resolved side inspectable. A rule the author cannot observe is folklore. ⚠ **Two different answers, and they are easy to confuse:** | you have | `osy model --json` gives you | |---|---| | a **component member** | a `side` — `server` / `client` / `either` | | a **top-level function** | an **`effects`** record — `readsData`, `writesData`, `pure`, `durability`, plus the entities read/created/modified — and its `transitive` closure | ⚑ **Probed.** A top-level function has **no `side` field**; its keys are `allowAnonymous · effects · file · isSystem · name · parameters · returnNullable · returns · scopedName · transitive · visibility`. The effects record is the answer for a function — `OpenOrders` reports `reads: [Order], readsData: true, pure: false`. *Informative.* The distinction is not an oversight. A component member is bound to one side because it is part of a rendered tree; a top-level function is frequently `Either` and takes its side from the caller, so "what does it touch" is the useful question and "where does it run" is not always answerable in isolation. ## 6.5 Forcing the side `[Server]` and `[Client]` exist. They force a member onto a side. **Reaching for one is almost always the wrong instinct.** They were de-advertised across **718 mentions in 174 files** on 2026-08-27, and removed from `osy init`'s scaffold — the first Osy# a downloader reads — precisely because their presence in examples taught readers to write them. The scaffold's explanatory comment was also false: it claimed a plain function runs on the server and a render expression cannot call one; measured, a plain pure top-level function *is* callable from a render. **Normative.** An implementation MUST NOT require these attributes for ordinary programs, and diagnostics MUST NOT suggest adding one as the remedy for an inference the author has not been shown. ## 6.6 What this section does NOT establish **UNVERIFIED, deliberately.** `osy validate` — the instrument behind every probe in this document — establishes what the compiler **accepts** and what it **reports**. It cannot establish: - that an inferred side is **correct at runtime** (that the server half really runs on the server); - **what crosses the wire** at a hand-off, and in which direction; - that a value which cannot cross is refused rather than silently dropped. Those are runtime semantics and need a test class, per §1.5. `ExecutionSidesHandlerTests` is the closest existing guard and is named here so the gap is addressable rather than merely admitted. **A future revision of this section MUST cite tests for the three claims above, or drop them.** --- **Next:** §9 Durability semantics — the other half of the model §11 depends on. **Drafted.** --- # §9 · Durability semantics > **Status: DRAFT.** The classification, its lattice, and where the compiler places a durable step are probed — > the first two through `osy model --json`, the third read from the resolver that performs the lowering. What a > **crash** actually does is runtime behaviour and is **UNVERIFIED here**; §9.7 names the guards. §11.1 and §11.2 both refuse a C# construct "because a call can suspend and resume in a different process". This section is that claim, stated properly. It is the reason the language has no `out` parameter and no `async`. ## 9.1 The premise **Normative.** A call MUST NOT assume that the process which began it is the process which finishes it. Everything below follows from that one sentence. An Osy# call may suspend — for a timer, for a human, for a child workflow — and resume later, elsewhere. So the stack frame is not a durable place: nothing may be written back into it (§11.1), and nothing may be scheduled against it (§11.2). ⭐ **The interesting consequence is that a re-run is normal, not exceptional.** A continuation-based engine replays nothing wholesale, but it does re-execute in two places: a statement is replayed after an in-process sub-call returns, and a statement that suspended is re-entered on resume. So "what does it cost to run this leaf twice" is a question the engine must be able to ask of every leaf in the program — which is what §9.2 is. ## 9.2 The durability classification Every leaf the language provides carries one of three values. | value | a re-run… | so it is | |---|---|---| | **Deterministic** | reproduces its value, and nothing escaped | free — never recorded | | **Nondeterministic** | yields a *different* value, but nothing left the platform | memoized on the per-statement node memo | | **External** | is a **second real-world effect** — a second charge, a second enqueue | given its own durable step | *Source: `StdlibDurability`, `Platform.Core/Dsl/OsySharp/Stdlib/OsySharpStdlib.cs`.* **Normative.** The three values form a **total order** — `Deterministic < Nondeterministic < External` — and the durability of a construct MUST be the maximum over its parts. That is what makes the classification usable as a lattice over whole programs rather than only over the leaves it was defined on. ⚠ **`External` is about *whose* system rolls back, not about I/O.** A commit to the application's own database is `Nondeterministic`: the platform owns the transaction. `File.WriteAllText` is `External`: the filesystem does not roll back because a later segment failed. ## 9.3 Asking a program what it costs **Normative.** An implementation MUST report the classification, and MUST report a witness for it. ⚑ **Probed 2026-08-27.** For a function whose body is `Security.RandomId()` and then `File.WriteAllText(path, id)` — a `Nondeterministic` leaf written *first* and an `External` leaf written *second* — `osy model --json` reports: ``` Archive direct: External durabilityVia = File.WriteAllText Wrapper direct: Deterministic via = (none) trans : External durabilityVia = Archive → File.WriteAllText ``` Three separable facts, each of which a reader would plausibly guess wrong: 1. **The lattice wins over source order.** `External` is reported although the nondeterministic call is written first. The value is a max, not a last-writer. 2. **`durabilityVia` is a path, not a name.** Through a call graph it reads `Archive → File.WriteAllText` — the route by which a plain-looking call reaches an egress. This is the field that makes the classification *actionable* rather than merely present. 3. **`effects` and `transitive` are different answers and both are given.** `Wrapper` calls nothing but `Archive`: it is `Deterministic` **directly** and `External` **transitively**. A reader who consults only one of them will be wrong about half the functions in any real program. ## 9.4 Where a durable step goes — the leaf, never the function **Normative.** An implementation MUST place the exactly-once boundary at the **egress leaf**, not at the enclosing function. ⭐ **This is the load-bearing design decision of the whole section.** If `Notify(u)` makes external calls A and then B, and the whole of `Notify` is one coarse step, a crash between A and B re-runs A on resume — a double send. Each egress is therefore its own step, and the deterministic orchestration between them re-runs freely, being a pure function of the memoized results. **It is automatic.** The resolver wraps every `External` leaf in a durable step during lowering. An author writes `Http.Get(url)` and gets exactly-once without naming it. `Workflow.Once("key", …)` remains available for a step the author wants to name or key, and an already-stepped leaf is not wrapped twice. ⚠ **So the transitive lattice of §9.3 does not decide anything.** It is an *author-facing* signal — "this plain-looking call reaches an egress". Step placement is a purely **local** decision at each leaf. Reading the lattice as the mechanism gets the model backwards, and is the likeliest misreading of this section. **A nondeterministic leaf gets no step, deliberately.** `DateTime.UtcNow` and `Guid.NewGuid` ride the per-statement node memo, which already serialises into the continuation. Giving each one its own out-of-band database write would be a real cost for a guarantee they already hold. Only egress — where the second execution reaches *someone else's* system — earns one. ⚑ **An unclassified target defaults to `External`.** A leaf missing from the durability table is treated as egress, so an omission over-protects rather than under-protects. *Informative:* the platform has been bitten by the resulting symptom more than once, which is itself the argument for the default being this way round. ## 9.5 A step wraps one thing ```osy probe=accepts int Charge(int amount) { return Workflow.Once("charge", () => amount * 2); } ``` ```osy probe=refuses RESOLVE_ERROR int Charge(int amount) { return Workflow.Once("charge", () => { var a = amount; return a; }); } ``` A step body is an **expression**. Statements go in a function, which the step then calls. ⚠ *Informative, and honest about a rough edge:* the refusal above is real and stable, but its diagnostic explains itself in terms of **query** lambdas ("a block can't lower to SQL in a query predicate") because block-bodied lambdas are refused language-wide from one site. At a durable-step call site that reason is not the applicable one. The refusal is right; the explanation is aimed elsewhere. Recorded as a §12 diagnostics concern. ## 9.6 `await` means *park* Restating §11.2 from this side, because it only makes sense here: `await Workflow.Run(…)` does not yield a thread. It **parks the run durably** — possibly for days — and resumes it in whatever process next picks it up. The keyword is reused because the English reading is right; the mechanism is this engine, not a task scheduler. ## 9.7 What this section does NOT establish **UNVERIFIED, deliberately.** Every claim above is about what the compiler *classifies* and *lowers*. None of it establishes what a crash does. Specifically unproven here: - that a step's result survives a process restart and is not re-executed on resume; - that a memoized nondeterministic value is the *same* value after resume; - that a durable step commits out-of-band, so a crash before the enclosing segment commits still finds it. Those need runtime tests. The guards that exist are `AutoDurableLoweringTests` (the leaf-level wrap), `WorkflowOnceDurableStepTests` and `WorkflowStepMemoIdentityTests` (memo identity across a resume), `DurableFunctionRunnerTests` (resume itself), and `FunctionEffectsDurabilityTests` with `OsySharpStdlibDurabilityTests` (the classification and its rollup). **A future revision MUST cite which of them proves which of the three claims above, or drop the claim.** --- **Next:** §8 Security as a language rule — the other declaration-time rule, and the one with the most surface. Not started. --- # §11 · Deliberate non-features > **Status: DRAFT.** Every refusal below is probed and run by CI (`SpecProbeGateTests`). The *reasons* are > informative; the refusals are normative. Most specifications list what a language has. This section lists what Osy# **refuses**, and why — because in every case here the reason is a property of the execution model rather than a matter of taste, and a reader who knows the reason can predict the next refusal instead of discovering it. ⚠ **These are not "not yet".** Each is a decision. Where a construct might arrive later, this section says so explicitly; where it cannot, it says that too. --- ## 11.1 `out` and `ref` PARAMETERS **Normative.** A parameter declaration MUST NOT carry `out` or `ref`. ```osy probe=refuses PARSE_ERROR int TryIt(string s, out int value) { value = 1; return 0; } ``` **Why, and it is the model rather than the taste.** A parameter passes a value **in**; only the return comes back out. An Osy# call can **suspend and resume in a different process** (§9), so there is no caller frame guaranteed to still be waiting for a write-back when the callee finishes. `out` is not merely unidiomatic here — its meaning depends on a stack frame the execution model does not promise to keep. ⚑ **A declaration cannot arrive later.** Its signature is the thing the durability model forbids, so this half is excluded by §9 rather than awaiting demand. Recorded as an owner decision, 2026-08-26. ### 11.1a ⛔ CORRECTION — a `TryParse` CALL SITE compiles, and this section said it could not **Normative.** `TryTTT(…, out var x)` on a stdlib parser IS accepted. ```osy probe=accepts decimal Parsed(string s) { if (decimal.TryParse(s, out var v)) { return v; } return 0m; } ``` Until 2026-08-29 this section asserted three things that are now false, and they are written out rather than edited away because a spec is read as authority: | it said | the truth | |---|---| | "A call site MUST NOT pass one" | a stdlib `TryParse` call site may | | "**there is no `TryParse`**" | there is | | the `Convert.ToInt` / `int.Parse` table was "the two real forms" | there are three | ⚠ **AND MY OWN GATE PASSED THROUGH THE CHANGE.** `SpecProbeGateTests` is built to fail in both directions — including on "a refusal the language no longer makes", which the plan calls the more dangerous kind of stale text. It did not fire, because **the probe was narrower than the claim**: the claim covered a declaration AND a call site; the probe only ever exercised a declaration. A gate is only as wide as the narrowest thing it actually runs, and a normative sentence with no probe under it is prose. ⚑ **The lesson for the rest of this document, and it is a rule now:** every clause of a normative sentence needs its own probe. Two clauses joined by "and" are two claims, and pinning one of them proves nothing about the other. ### 11.1b How it works, given `out` is refused **`out` is never accepted — the call is REWRITTEN before resolution.** `decimal.TryParse(s, out var v)` becomes, hoisted ahead of its statement: ``` decimal? v = null; try { v = decimal.Parse(s); } catch { } ``` with `v != null` left in the call's place. So no `out` reaches the resolved tree: there is no write-back, no caller frame to survive a suspension, and nothing for §9 to forbid. **The nullable local is the did-it-work channel** — the shape Osy# already uses everywhere — and `TryParse` is C# spelling the compiler translates into it. *Informative — why the two halves differ.* A DECLARATION is a signature the author writes and the durability model cannot honour. A CALL SITE is a shape the compiler owns end to end, so it can be rewritten out of existence. The durability argument bites on the first and has nothing to say about the second. ⚑ **And it declines by POSITION, which is the tell that this is a rewrite rather than support.** The hoist needs somewhere to go, so a loop CONDITION or a lambda BODY is refused — there the parse would have to happen per iteration or per element rather than once before. The diagnostic prints the whole mechanism and the remedy for each position, which is why this section can describe it without reading the resolver. --- ## 11.2 `await` on an ordinary call **Normative.** `await` MUST NOT be applied to an ordinary function call. ```osy probe=refuses RESOLVE_ERROR int Inner() { return 1; } int Outer() { var v = await Inner(); return v; } ``` **Why.** Effects run **in place**. There is no async/await colouring in Osy#, because there is nothing for it to distinguish: a call that performs I/O and a call that does not are written and read the same way, and the runtime decides how to execute them. **The one exception is `await Workflow.Run(...)`** — a Saga-style durable wait on a *child workflow* (§9). That is not the C# meaning of `await`. It does not yield a thread and resume shortly after; it **parks the run durably**, possibly for days, and resumes it in whatever process picks it up. The keyword is reused because the reading is right — "continue when that finishes" — but the mechanism is the durable engine, not a task scheduler. *Informative.* This is why §11.1 and §11.2 belong together: both follow from a call not owning a stack frame for its own lifetime. --- ## 11.3 `Now` **Normative.** The identifier `Now` MUST NOT resolve. It is not merely deprecated — the name is absent from app-source resolution entirely, and answers exactly what any undefined name answers. ```osy probe=refuses RESOLVE_ERROR DateTime When() { return Now.Utc; } ``` **Write `DateTime.UtcNow`.** The compiler lowers it to the ambient clock, so it is testable (`TestClock.*`) and correct inside a `live var`, a render slot, and a durable body alike. ⚑ **Why the name is hidden rather than deprecated.** A retirement *message* was tried first and made things worse: `Osysharp.Now` is a real class in the model, so with the refusal removed `Now.Utc` resolved far enough to answer *"'Osysharp.Now.Utc' is an instance member"* — which still tells the reader the class is there. Worse, a typo'd `Nowt` produced *"Did you mean 'Osysharp.Now'?"*: the compiler proactively recommending a name it would then refuse. Hiding the name from resolution is what makes the removal complete. --- ## 11.4 A retired spelling is deleted, not aliased **Normative.** A renamed surface MUST NOT keep its old spelling as an alias. | retired | current | |---|---| | `[Display]` | `[Label]` | | `Modes(light:, dark:)` | `Modes.Of(light:, dark:)` | | `.migration.osy` | `.migration` | *Informative.* Osy# has no released versions and no deployed programs outside this repository, so an alias would preserve compatibility with nothing while doubling the surface a reader must learn and a diagnostic must consider. The rule is expected to change when the language ships a stable release; §13 will say how. --- ## 11.5 What is NOT in this section Two things are frequently assumed to be deliberate refusals and are not: - **`[Server]` / `[Client]` annotations.** These exist. They are a forcing hatch, and reaching for one is almost always the wrong instinct — the side is inferred (§6). They were de-advertised across 174 files on 2026-08-27 precisely because their presence in examples taught readers to write them. Absent from your source is the normal case, not a refusal. - **A scalar array on an entity** (`string[] Tags;`). Refused today, with a diagnostic naming the two real options — but this is a **gap**, not a decision, and it is tracked as such. **UNVERIFIED** here: no probe written. --- **Next:** §6 The execution-side model and §9 Durability semantics — the two rules §11.1 and §11.2 both depend on. **Both drafted.** --- # Agents (calling a model like anything else you declared) > An `agent` is a declaration — instructions, tools, model — and calling it is calling a name. The first-day mistake is treating the call as a chat: you hand it the turns you want it to see, so what it remembers is what you passed, and every run is recorded as a task with its cost and outcome whether you look or not. ## Summary {#summary} **An agent is something you declare, and calling it is calling a name.** Its declaration supplies its instructions, its tools and its model, so the call site stays about what you are asking rather than about how the model is configured. ```osy title="the call is a call" test app=agent-index using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(100)] string DisplayName; security { allow read when IsAuthenticated; allow create when IsAuthenticated || IsAnonymous; } } agent Support { Purpose = "Answer questions about an order."; Prompt = "You answer order questions from the context you are given."; Principal = new User { DisplayName = "Support" }; } string Answer(string question) { var turns = new List(); turns.Add(Turn.User(question)); return Support.Ask(turns).Text; } ``` ## Description {#description} **You hand it the turns it should see.** There is no hidden session: the question, the history worth replaying and the context you assembled are the argument ([running an agent from your code](https://osysharp.com/reference/agent/ask/)). What it "remembers" is what you passed — see [agent conversation memory (using Osysharp.Agents)](https://osysharp.com/reference/agent/conversation-memory/) for the shapes that are worth passing and the ones that are not. **Every run is a task, recorded.** Cost, duration and outcome are captured whether or not you look ([the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/)). [watching a task run (task.Watch)](https://osysharp.com/reference/agent/task-watch/) follows one in flight, [what the agent saw (task.Transcript)](https://osysharp.com/reference/agent/task-transcript/) reads what it actually said and did, [what a task cost, and what it did (task.Calls)](https://osysharp.com/reference/agent/task-calls/) lists the tools it reached for, and [stopping work (task.Stop)](https://osysharp.com/reference/agent/task-stop/) ends one. **The model is a declaration, not a call-site argument.** [app.Models — the models an app admits, each with a name](https://osysharp.com/reference/agent/models/) is how a model is named and [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) what a call gets when it names none — so changing which model an agent uses is an edit in one place, not a sweep of call sites. **A long-running agent is a workflow, not a loop you write.** [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) is the shape for repeated turns, and [an agent asking a person (the human slot)](https://osysharp.com/reference/agent/hitl/) is how a person is brought into one — which is a parking point, with everything the workflow area says about surviving a deploy. [what an agent hands back (AgentDeliverable)](https://osysharp.com/reference/agent/deliverables/) is how a run's output becomes something the app holds. ## The pages {#the-pages} Run `osy docs agent` for the full listing. - **Calling one** — [running an agent from your code](https://osysharp.com/reference/agent/ask/), [agent conversation memory (using Osysharp.Agents)](https://osysharp.com/reference/agent/conversation-memory/), [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) - **Which model** — [app.Models — the models an app admits, each with a name](https://osysharp.com/reference/agent/models/), [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) - **Turning it off** — [turning AI off (the runtime switch)](https://osysharp.com/reference/agent/ai-switch/), the operator's runtime disable - **Capping it** — [LLM budgets (hard daily limits per organisation, app and user)](https://osysharp.com/reference/agent/llm-budget/), hard daily budgets per organisation, app and user, enforced before the call leaves - **People in the loop** — [an agent asking a person (the human slot)](https://osysharp.com/reference/agent/hitl/), [what an agent hands back (AgentDeliverable)](https://osysharp.com/reference/agent/deliverables/) - **Watching a run** — [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/), [watching a task run (task.Watch)](https://osysharp.com/reference/agent/task-watch/), [what the agent saw (task.Transcript)](https://osysharp.com/reference/agent/task-transcript/), [what a task cost, and what it did (task.Calls)](https://osysharp.com/reference/agent/task-calls/), [stopping work (task.Stop)](https://osysharp.com/reference/agent/task-stop/) ## See also {#see-also} - [running an agent from your code](https://osysharp.com/reference/agent/ask/) — the call, and what a turn list is for - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — what every run records, without being asked - [an agent asking a person (the human slot)](https://osysharp.com/reference/agent/hitl/) — bringing a person in, and why that makes it a parking point --- # LLM budgets (hard daily limits per organisation, app and user) > Every model call an application makes is metered, and the platform refuses a call before it leaves when the day's budget is spent. Budgets are set by the organisation's owner in the admin — per organisation and per application, in tokens and optionally in dollars — and per user through an app-local override. A budget that cannot be verified refuses too (fail-closed). A refused call fails with a message naming the scope, the limit and the usage; it never silently returns nothing. ## Summary {#summary} Beside the [runtime switch](https://osysharp.com/reference/agent/ai-switch/) sits the dial. The platform meters every LLM and embedding call an application makes and enforces **hard daily budgets before the call leaves**: a call that would exceed the day's limit is refused, not sent. Nobody wakes up to a bill because an agent looped overnight — the eleventh call over the cap is refused, and the application carries on without it. Three scopes, checked in order, any one of which can refuse: | Scope | Set where | Limits | |---|---|---| | **the organisation** | admin → org → Budgets, by the org's Owner (or a platform admin) | daily LLM tokens · daily embedding tokens · an optional daily USD cap | | **the application** | the same page, per app | the same three, plus the **default per-user daily token limit** for the app | | **one user of the app** | the app itself, through `UserLlmBudget` (this page's Osy# surface) | that user's daily LLM tokens; `0` blocks them | The budget day starts at midnight in the budget's own time zone (the organisation's, when set), not the server's. ## Signature {#signature} ```text admin → org → Budgets Daily LLM tokens ______ (blank = platform default · 0 = blocked) Daily embedding tokens ______ Daily USD cap ______ (blank = no cost cap; the token limit is the floor) Default per-user tokens ______ (application rows only) ``` ```osy syntax using Osysharp.Llm.Budget; // and `use Osysharp.Llm.Budget;` in app.osy entity UserLlmBudget { // provided by the capability — one row per user, optional principal UserId; // the app-local user this override applies to long DailyLlmTokenLimit; // input + output tokens per budget day; 0 = blocked } ``` An application never declares its own organisation or application cap in source: those are the operator's, set outside the app's reach for the same reason the [switch](https://osysharp.com/reference/agent/ai-switch/) is. What an application *can* do is narrow the per-user limit below the app default, row by row. ## Description {#description} ### How a call is metered {#metering} Before a model call is sent, the gate **reserves** the estimated tokens against each scope in one atomic statement — check and increment together, so two concurrent calls cannot both squeeze under a limit. After the response it **settles** the reservation to the actual tokens. Usage is recorded per scope, per day, per model, so the admin's budgets page shows today's spend against the cap, and the [audit trail](https://osysharp.com/reference/config/audit/)'s `LlmCallRecord` carries the same numbers per call. ### What a refusal looks like {#refusal} A refused call throws. The message names the scope, the limit and the usage, and says when the day resets: ```text Daily LLM token budget for this application (2,000,000 tokens) is exhausted (2,000,113 used); resets at 00:00 Europe/Stockholm. ``` Over HTTP the platform answers **429**; in a workflow or a background handler the refusal is terminal for that call — it is logged and not retried, because a retry storm on an exhausted budget is exactly what a budget exists to prevent. In Osy# it is an ordinary exception: catch it where the application has a sensible way to go on without the model — the same degraded path the switch uses. ```osy syntax try { var reply = Screener.Ask(turns); } catch (Exception e) { // budget exhausted, or AI switched off: the report is screened by the rules alone report.ScreeningSkipped = true; } ``` ### Fail-closed {#fail-closed} If a budget cannot be verified — the admin row cannot be read, the accounting statement fails — the call is **refused**, with a message that says so rather than one that claims exhaustion. A budget that fails open is not a budget; measured once on this platform (an incident on 2026-06-12) and the gate has refused on doubt since. ### Per-user overrides {#per-user} The application's default per-user limit comes from the admin. An app that wants to give one person more, or block one, writes a `UserLlmBudget` row — an ordinary entity under the app's own `security { }`, so who may set it is the app's rule: ```osy title="a per-user override the app's admin may set" test app=agent-llm-budget using Osysharp.Llm.Budget; [Role] enum Role { Authenticator, Admin } entity RoleGrant { [Required] User User; [Required] Role Role; security { allow read when IsAuthenticated; allow create when IsAuthenticator; } } policy IsAuthenticator => RoleGrant.Any(g => g.User == user && g.Role == Role.Authenticator); policy IsAdmin => RoleGrant.Any(g => g.User == user && g.Role == Role.Admin); [Principal] entity User { [Required, Unique, MaxLength(200)] string Email; [MaxLength(200)] string PasswordHash; security { allow read when IsAuthenticated; allow read, create when IsAuthenticator; deny read PasswordHash when !IsAuthenticator; } } // The capability's entity, reopened only to say who may write it: the app's Admin. partial entity UserLlmBudget { security { allow read, create, update when IsAdmin; } } void CapUser(User u, long tokensPerDay) { var b = UserLlmBudget.Where(x => x.UserId == u).FirstOrDefault(); if (b == null) { new UserLlmBudget { UserId = u, DailyLlmTokenLimit = tokensPerDay }; } else { b.DailyLlmTokenLimit = tokensPerDay; } } [AuthMethod] string Login(string email, string password) { var u = User.Where(x => x.Email == email).FirstOrDefault(); if (u == null) { Security.VerifyPassword(password); return ""; } if (Security.VerifyPassword(password, u.PasswordHash)) { return Security.IssueJwt(u.Id, u.Email); } return ""; } app.Auth = new PasswordAuth { LoginField = Email, PasswordField = PasswordHash }; app.AuthBootstrap = new AuthBootstrap { Login = Login, Role = Role.Authenticator }; ``` A user with no row gets the application's default; a row with `0` blocks that user's model calls entirely while everyone else's continue. ### What it answers for procurement {#procurement} The switch answers *can it be turned off*. The budget answers *what is the most it can ever cost us in a day* — per organisation, per application, per person, enforced by the platform rather than promised by the application, and visible on one admin page against today's usage. ## Examples {#examples} An organisation caps itself at a dollar a day and one application at a fifth of that: ```text title="two caps, and the day they reset in" admin → org "Acme" → Budgets daily USD cap 1.00 · zone Europe/Stockholm admin → org "Acme" → app "Desk" → Budgets daily USD cap 0.20 · default per-user tokens 50,000 ``` The twentieth cent Desk would spend is refused; Acme's other apps keep their share; the person the app's admin capped at 0 with `CapUser(u, 0)` is refused before the app's cap is ever consulted. ## See also {#see-also} - [turning AI off (the runtime switch)](https://osysharp.com/reference/agent/ai-switch/) — the switch this dial sits beside: off in seconds, from the same control plane - [what a task cost, and what it did (task.Calls)](https://osysharp.com/reference/agent/task-calls/) — where a task's own calls and their cost are read back in the app - [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) — `LlmCallRecord`, the per-call trail with the same numbers and its own retention - [Agents (calling a model like anything else you declared)](https://osysharp.com/reference/agent/index/) — the rest of the agent and model surface --- # agent conversation memory (using Osysharp.Agents) > A conversation is stored as a `ChatSession` plus its `ChatMessage` turns, so an agent asked a follow-up can refer back to what was said earlier. Both ride `Osysharp.Agents` — the same capability an agent declaration already needs — so there is nothing extra to opt into. An agent stays stateless until a call names a conversation. A conversation belongs to the user who started it and is readable only by them. ## Summary {#summary} An agent is **stateless by default**. Each turn is answered on its own: nothing from the previous exchange is in scope unless a call names the conversation it belongs to. That is the right shape for an agent that classifies a document or answers one question. A conversation is stored as a **`ChatSession`** with its turns as **`ChatMessage`** rows, and an agent asked a follow-up can see what came before. Both entities ride `Osysharp.Agents` — the capability an `agent` declaration already requires — so a conversation needs no second import. ```osy syntax using Osysharp.Agents; ``` ## Signature {#signature} ```osy syntax using Osysharp.Agents; ``` Two entities enter the app's model: | entity | what it holds | |---|---| | `ChatSession` | one conversation — which agent, its title, when it was last active, who it belongs to, and optionally the record it is about | | `ChatMessage` | one turn — a user message, an assistant reply, a tool call or a tool result, in `Sequence` order | ## Description {#description} **Conversations are part of what the agent surface is.** They are not a second thing to import: a session and its turns are what an agent that holds a conversation, parks for a human, or reports an outcome would otherwise re-implement, so they ride `Osysharp.Agents` itself. Nothing about your agents changes to get them: the same agent declaration, the same calls. **Which conversation, if any, is decided per call.** A request that carries a `conversationId` continues that conversation; one that does not starts a new one. An app whose agents only ever classify a document names no conversation and its tables stay empty. **A conversation belongs to one user.** It is stamped with the user who created it, listings return only that user's conversations, and asking for someone else's by id answers `404` — the same answer as an id that does not exist, so no one can probe for which conversations exist. Anonymous visitors own no conversations: an anonymous caller gets an empty list, and creating one requires a signed-in user. **A long conversation is summarised rather than truncated.** When the history outgrows the model's context window, earlier turns are replaced by a summary turn, so the beginning of the conversation is still represented instead of being dropped. **Entity context is optional.** A conversation can record the record it is about — "ask the agent about *this* order" — so it can be listed alongside that record rather than in one undifferentiated pile. ## Examples {#examples} An app whose agent holds a conversation: ```osy title="conversation-memory-optin" test app=conversation-memory-optin using Osysharp.Agents; [Principal] entity User { [MaxLength(255)] string Email; } entity Order { [Required, MaxLength(50)] string Reference; } ``` A chat request that carries a `conversationId` continues that conversation; one that does not starts a new one. ## See also {#see-also} - [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — the model an agent talks to. --- # an agent asking a person (the human slot) > An agent that needs something only a person can supply does not guess and does not fail — it asks, and its work PARKS. The wait becomes a modelled fact with an assignee and a clock, not a paused process. Hours later the answer arrives as the result of the question it asked, and the same work carries on. Asking is available to any agent running inside a loop, and nothing is declared to enable it. ## Summary {#summary} An agent working on something real will sometimes reach a point only a person can settle. A charge nobody can explain from the record. A judgement that is somebody's to make. The two obvious ways out are both bad: guessing produces a confident wrong answer, and failing throws away the work already done. So it asks. The run **parks**, the question goes in front of a person, and when they answer, the work continues from exactly where it stopped. ```osy title="the ask that parks — branch and go wait" syntax var reply = Auditor.Ask(turns); if (reply.Parked) { // `reply.Question` is what it wants to know. Put it in front of somebody. goto Waiting; } ``` …and later, when they have replied: ```osy title="hours later, the answer resumes the same run" syntax var reply = Auditor.Answer(this.Item, "A client dinner for four — I paid for all."); ``` ## Signature {#signature} ```osy syntax .Answer(task, text) // → AgentReply ``` | | | |---|---| | `task` | the task whose run is parked — inside a loop that is `this.Item`. Must be an `AgentTask` or one of your types deriving from it | | `text` | what the person said, verbatim. It reaches the agent as the answer to the question it asked | | returns | an `AgentReply`, exactly as [`Ask`](https://osysharp.com/reference/agent/ask/) does — **because a resumed run can park again** | ## Description {#description} ### Asking comes from the loop, and is declared nowhere {#capability} An agent running inside a [loop](https://osysharp.com/reference/agent/loop/) can ask a person. An agent that is not, cannot — the verb is not offered to it at all. That is not a restriction, it is the only honest answer. Parking means *"stop here and come back when somebody replies"*, and coming back is the loop's doing: a loop is checked at compile time to declare a `Waiting` state, so an agent inside one always has somewhere to park. An agent with no loop has nowhere. Letting it park anyway would produce work that waits forever — and on every screen, work waiting forever looks exactly like work waiting patiently for a person. ⚑ So the capability follows from the structure rather than from a flag. There is nothing to switch on, nothing to forget, and no way to end up with an agent that can ask but cannot be answered. ### Nothing is suspended, and nothing needs to be {#mechanism} This is the part worth understanding, because it explains every other rule on this page. An agent's turn loop is ordinary code — call the model, run the tools it asks for, repeat. It cannot be frozen across the hours a person takes to reply, and no amount of machinery would change that. It does not have to be. **An agent's state is its conversation**, and that is already durable: 1. The agent calls the ask verb. That turn is written down **with no result** — an unanswered question is exactly what a parked run looks like. 2. Everything stops. The task reads `Waiting`; the workflow holds the wait as a `Slot` with an assignee, an opened-at and an SLA clock. 3. The person answers. Their words are written as **that call's result**. 4. A fresh run replays the conversation — the original instruction, the agent's own question, and now its answer — and the model carries on as though it had called a very slow tool. Nothing was suspended, so nothing has to be woken. This is also why an agent that keeps no conversation cannot do any of it, and why that is refused **at the ask** rather than discovered at the answer. ### An agent that retains nothing is refused when it asks {#memory-required} Asking requires `Memory = Persistent` on the agent. Its history *is* its continuation, so an agent with none has nothing to come back to. The refusal happens the moment it tries to ask, not later when somebody answers — because a run that parks and can never be resumed is a dead end, and a dead end is indistinguishable from patience on every screen you would look at. The message names the one line that fixes it. ### Parking again is ordinary {#park-again} `Answer` returns an `AgentReply`, and it can come back parked. An answer that raises one more question is what conversations do. Branch on it, or you will move to a terminal state over work that is still waiting on somebody: ```osy syntax on Answered(string text, Slot slot) { var reply = Auditor.Answer(this.Item, text); if (reply.Parked) { goto Waiting; } // it asked one more thing goto Completed; } ``` ### What the platform owns, and what you own {#split} | | | |---|---| | **The platform** | that the run can park at all; that the wait is a `Slot` with an assignee, an opened-at and a clock; that the answer arrives as the question's result; that the same task and the same conversation carry on | | **You** | who is asked · how they hear about it · what the question looks like on screen · how long they get · what happens if they never reply | The second column is not an oversight. Any opinion the platform held about who to notify would be wrong in every app that disagreed — so the `Waiting` state's `enter` body is yours, and so is whatever row you write to put the question in front of somebody. ### Answering goes through the slot {#answering} Deposit the answer into the workflow slot rather than calling `Answer` from a page. The slot is what decides whether *this* caller may answer, and what records that they did and how long they took — which is what makes *"it waited 15 hours for Sam"* a question with an answer instead of a shrug. ```osy syntax void AnswerAuditor(Question question, string text) { ReviewClaim.For(question.Task).Filer.Answered(text); } ``` The workflow's own `on Answered` arm is what calls `Answer`. Depositing is server-side because the authority check is: a browser cannot decide who is allowed to answer. ### What the person is shown {#question} `reply.Question` is what the agent asked, in its own words. It is handed back rather than dropped because it is the whole content of the work item — an inbox that knows an agent is waiting but not what it wants is not an inbox. Write it somewhere your own screens can read. What that row looks like is yours; the demo keeps a `Question` row against the claim, and renders it at the top of the page the person is already on. ## Examples {#examples} The smallest app in which an agent can ask a person. Everything here exists to make the two marked lines reachable — the agent's work runs inside a loop, so it may ask; and the answer goes in through the slot: ```osy title="agent-asks-a-person" test app=agent-hitl using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity Claim { [Required, MaxLength(200)] string Title; security { allow read, create, update when IsAuthenticated; } } /// What the agent asked. The platform parks the run; this row is what a person actually sees. entity Question { [Required] ReviewTask Task; [Required, MaxLength(2000)] string Text; [MaxLength(2000)] string? Answer; security { allow read, create, update when IsAuthenticated; } } entity ReviewTask : AgentTask { security { allow read when IsAuthenticated; } } agent Auditor { Purpose = "Review a claim."; Prompt = "You review expense claims."; Memory = Persistent; // required: an agent that retains nothing cannot come back Principal = new User { Email = "auditor@example.com" }; Loop = ReviewClaim; // …and this is what lets it ask at all } workflow ReviewClaim { Tracks = ReviewTask.Status; Autostart = true; Initial = Running; event Answered(string text); state Running { enter { var turns = new List(); turns.Add(Turn.User("Review this claim.")); var reply = Auditor.Ask(turns); if (reply.Parked) { // ← IT ASKED SOMEBODY Ask(this.Item, reply.Question ?? ""); goto Waiting; } goto Completed; } } state Waiting { subscribe Answered(string text) as Filer { Candidates = u => u.Email != ""; Finished { Within = TimeSpan.FromDays(2); Unfinished { goto Failed; } } } on Answered(string text, Slot slot) { var reply = Auditor.Answer(this.Item, text); // ← AND THIS IS THE ANSWER REACHING IT Close(this.Item, text); if (reply.Parked) { goto Waiting; } goto Completed; } } terminal success Completed { } terminal error Failed { Message = "the review could not be completed"; } } void Ask(ReviewTask task, string text) { var q = new Question { Task = task, Text = text }; UnitOfWork.Commit(); } void Close(ReviewTask task, string text) { var open = Question.Where(q => q.Task == task && q.Answer == null).FirstOrDefault(); if (open != null) { open.Answer = text; UnitOfWork.Commit(); } } /// What your page calls when the person replies. void AnswerAuditor(Guid questionId, string text) { var question = Question.Where(q => q.Id == questionId).FirstOrDefault(); ReviewClaim.For(question.Task).Filer.Answered(text); } ``` The same example with the surrounding app — a real claim, a filer, and the trigger that starts the work — is on [[agent-loop#examples|the loop page]]. ## See also {#see-also} - [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) — the workflow the work runs inside, and what makes asking possible - [running an agent from your code](https://osysharp.com/reference/agent/ask/) — running a declared agent, and the `AgentReply` both verbs answer - [Workflow.Work<T> (everything outstanding) and its SLA numbers](https://osysharp.com/reference/workflow/work/) — slots, assignees and SLA clocks: what a wait is made of - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — the task that stays open while the run is parked --- # app.Models — the models an app admits, each with a name > `app.Models` declares more than one model your app may use, each under a name you choose. The name is what your code and your users refer to — `Llm.Fast` — so a call site never quotes a provider's model string, and pointing a name at a different model is a one-line change. ## Summary {#summary} [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) declares one model. `app.Models` declares several, each under a name — so your app can offer a choice, or use a cheap model for one job and a strong one for another. ## Signature {#signature} ```osy syntax app.Models = [ new LlmConfig("") { Provider = LlmProvider.X, Model = "…", ApiKey = Secret.X, BaseUrl = "…" }, … ]; app.DefaultModel = Llm.; ``` ## Description {#description} Each entry is the same `LlmConfig` you would write for a single default, plus a **name of your choosing**. **The name is a real name, not a string.** You refer to it as `Llm.Fast`, and a name nothing declares is a compile error that lists what you did declare. So a typo fails the build rather than quietly matching no model, and renaming an entry breaks every place that used it — which is what you want, because those are the places that need updating. **Name the models for what they are to your app, not for what the vendor calls them.** `Llm.Fast` and `Llm.Smart` stay true when you point them at newer models next month; `Llm.Haiku` becomes a lie. The name is also what your users see if you build a picker. **`app.DefaultModel` says which one serves a call that does not ask for a particular model:** ```osy syntax app.DefaultModel = Llm.Fast; ``` Pointing the default at a name rather than repeating the settings means there is one description of each model, so the default can never disagree with the entry it names. You can still write `app.DefaultModel = new LlmConfig { … }` directly — that is the right form for an app with only one model, and it keeps working unchanged. **Your app can only use models it declares.** Naming one at a call site can narrow the choice to any declared model, but never reach one you did not declare — that is refused, with a reason, rather than quietly served by something else. `app.Models` is how a model becomes available to be chosen. **Removing an entry removes the model.** The list is reconciled against your source on every compile, so deleting a line withdraws that model from the app rather than leaving it behind. `DefaultModel` is a reserved name — it is how the default itself is stored — so an entry cannot be called that. ## Examples {#examples} Two models, one of them the default: ```osy title="two models from one provider, one of them the default" test app=models-two app.Secrets = [ new Secret("Anthropic") ]; app.Models = [ new LlmConfig("Fast") { Provider = LlmProvider.Anthropic, Model = "claude-haiku-4-5", ApiKey = Secret.Anthropic }, new LlmConfig("Smart") { Provider = LlmProvider.Anthropic, Model = "claude-opus-5", ApiKey = Secret.Anthropic }, ]; app.DefaultModel = Llm.Fast; entity Note { [MaxLength(140)] string Title; } ``` Models from two different providers, which is the case a single default cannot express at all: ```osy title="two different providers — what a single default cannot express" test app=models-two-providers app.Secrets = [ new Secret("Anthropic"), new Secret("OpenAI") ]; app.Models = [ new LlmConfig("Writer") { Provider = LlmProvider.Anthropic, Model = "claude-opus-5", ApiKey = Secret.Anthropic }, new LlmConfig("Checker") { Provider = LlmProvider.OpenAI, Model = "gpt-5", ApiKey = Secret.OpenAI }, ]; app.DefaultModel = Llm.Writer; entity Draft { [MaxLength(140)] string Title; } ``` ## See also {#see-also} - [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — declaring a single model, for an app that needs only one - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — where the `Secret.X` an entry names comes from - [LlmClient.Stream — a model's answer as it is written](https://osysharp.com/reference/function/llm-stream/) — calling a model --- # default LLM model (app.DefaultModel) > Declares the app's default LLM — the provider, model, API-key secret, and optional endpoint — as a single app-level config. `Provider` is one of `LlmProvider.Anthropic | OpenAI | Gemini | OpenAICompatible`; the API key is a `Secret.X` handle declared in `app.Secrets`. A singleton: declaring it twice is a compile error, and removing it clears the default. ## Summary {#summary} `app.DefaultModel` declares the application's default large-language model as one app-level config block. You name a **provider**, a **model** string, the **API key** (a `Secret.X` handle), and an optional custom **BaseUrl**. It is a per-app **singleton** — declared once — and it self-reconciles against source: removing it clears the default. ```osy syntax app.Secrets = [ new Secret("Anthropic") ]; app.DefaultModel = new LlmConfig { Provider = LlmProvider.Anthropic, Model = "claude-opus-4-8", ApiKey = Secret.Anthropic, }; ``` ## Signature {#signature} ```osy app.Secrets = [ new Secret("Anthropic") ]; // the handle the config below reads app.DefaultModel = new LlmConfig { Provider = LlmProvider.Anthropic, // Anthropic | OpenAI | Gemini | OpenAICompatible Model = "claude-opus-4-8", // the provider's model id ApiKey = Secret.Anthropic, // a handle declared in app.Secrets BaseUrl = "https://api.anthropic.com", // optional — required for OpenAICompatible }; ``` A single app-level assignment. It is a singleton — declaring it twice is a compile error. ## Description {#description} `LlmConfig` has four members: - **`Provider`** — a qualified `LlmProvider` enum member. `Anthropic`, `OpenAI`, and `Gemini` are first-party providers reached at their default endpoints. `OpenAICompatible` targets any OpenAI-wire-compatible server (a self-hosted model, a proxy, or an OpenRouter-style gateway) and **requires** a `BaseUrl`. - **`Model`** — the provider's model identifier (e.g. `claude-opus-4-8`, `gpt-4o`, `gemini-2.5-flash`). - **`ApiKey`** — a `Secret.X` handle. The secret must be declared in [`app.Secrets`](https://osysharp.com/reference/config/secrets/); the key is resolved at runtime from the secret store and never inlined in source. - **`BaseUrl`** *(optional)* — a custom endpoint. Optional for the first-party providers (they default to their own endpoints); required for `OpenAICompatible`. Because it self-reconciles against source, the config behaves like a switch: **declaring it** upserts the singleton, **removing it** sweeps the row and clears the app default (no prune step needed). Every LLM call the platform makes on your behalf is metered against your budget regardless of which provider you choose. ## Examples {#examples} Point the app at an OpenAI-compatible endpoint you host yourself — `OpenAICompatible` plus a `BaseUrl`: ```osy title="default-model-openai-compatible" test app=default-model-openai-compatible app.Secrets = [ new Secret("LocalLlm") ]; app.DefaultModel = new LlmConfig { Provider = LlmProvider.OpenAICompatible, Model = "llama-3.1-70b", ApiKey = Secret.LocalLlm, BaseUrl = "https://llm.internal.example.com/v1", }; ``` ## See also {#see-also} - [[Searchable]](https://osysharp.com/reference/memory/searchable/) — `[Searchable]`, the field-search surface; semantic ranking uses the app embedding configured the same way --- # running an agent from your code > Call an agent you declared the way you would call anything else you declared — by name. You hand it the turns you want it to see: the question, the history worth replaying, the context you assembled. Its own declaration supplies its instructions, its tools and its model, so the call site stays about what you are asking. The answer comes back as a string, and the run is recorded as a task with its cost and its outcome. ## Summary {#summary} An agent is something you declare, so it is something you can call: ```osy syntax var reply = Triager.Ask(turns); if (reply.Parked) { /* it asked a person */ } else { /* reply.Text */ } ``` The receiver is the agent's own name. That is not decoration — it means the compiler checks the agent exists, the same way it checks any other name you write, instead of finding out at run time that a string was misspelled. ## Signature {#signature} ```osy syntax List turns = new List(); turns.Add(Turn.Context("Acme Ltd, plan Enterprise, customer since 2019")); turns.Add(Turn.User("Is the Lisbon dinner within policy?")); AgentReply reply = Triager.Ask(turns); string answer = reply.Text; ``` | you write | it means | |---|---| | `Turn.User(text)` | somebody is asking | | `Turn.Assistant(text)` | the agent said this earlier — replayed history | | `Turn.Context(text)` | facts you supplied. Not dialogue | | `.Ask(turns)` | run that agent over those turns; answers an `AgentReply` | | `.StartTask(trigger)` | hand the work to the agent's [[agent-loop\|loop]] instead of running it here | ## Description {#description} **You assemble the turns, and that is deliberate.** Which history to replay and which facts to include are product decisions — a support screen sends the customer and their recent orders, a nightly audit sends one line. A platform that guessed for you would guess wrong in both directions: too much costs money on every call, too little produces a confident answer to a question the agent could not actually see. ⚑ **Say which kind each turn is.** `Turn.Context` is the one people skip, and it is the one that matters most: an agent that cannot tell the facts it was handed from the question it was asked will answer the facts. Reading back a customer record is a very convincing wrong answer. **The agent brings itself.** Its instructions, its tools, its model and its memory are on its declaration, so they are not repeated at the call site and cannot drift between two places that call the same agent. **Everything the run did is recorded.** The call returns the answer; the rest is a task — what it cost, what it called, how long it waited, and what it produced. See [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) and [what an agent hands back (AgentDeliverable)](https://osysharp.com/reference/agent/deliverables/). That is why the return is a plain string rather than a result object: the interesting detail is queryable, and putting it in the return type would make every call site hold something it did not ask for. **A repeated run does not repeat the call.** If the work is resumed after an interruption, the answer already given is the answer used — the agent is not asked twice. That matters for cost, and because the same question need not produce the same answer twice. ⚠ **Asking a person suspends the work.** If the agent decides it needs a human, the run stops and waits rather than inventing an answer, and `Ask` says so instead of returning an empty string. The waiting run is recorded and can be picked up once somebody answers. ## Examples {#examples} Checking something with the context the app already has: ```osy title="ask-an-agent" test app=agent-ask using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(100)] string DisplayName; security { allow read when IsAuthenticated; allow create when IsAuthenticated || IsAnonymous; } } agent Triager { Purpose = "Triage expense reports."; Prompt = "You triage expenses against the travel policy."; Principal = new User { DisplayName = "Triager" }; } string Check(string question, string customer) { var turns = new List(); turns.Add(Turn.Context(customer)); turns.Add(Turn.User(question)); return Triager.Ask(turns).Text; } ``` ### The agent may stop to ask a PERSON {#parked} An agent that needs something only a human can supply does not fail and does not guess — it stops and asks. `Ask` answers that as an outcome you branch on rather than an error thrown out from under you: ```osy syntax var reply = Triager.Ask(turns); if (reply.Parked) { // The run is recorded and resumable. `reply.Question` is what it wants to know — // put it in front of a person, and the run continues when they answer. return reply.Question; } return reply.Text; ``` | member | | |---|---| | `Text` | what the agent said. Empty when parked — never null, so emptiness never has to mean two things | | `Parked` | it stopped to ask a person, and is waiting | | `Question` | what it asked, when parked | ⚠ **Branch on `Parked`, not on an empty `Text`.** An agent may legitimately reply with nothing, so the two are deliberately different answers. ### Handing the work to the loop instead {#start-task} `Ask` runs the agent *now* and waits. When the work is big enough to deserve durability, a human step or a retry, hand it to the agent's [loop](https://osysharp.com/reference/agent/loop/) instead: ```osy title="handing the work to the loop instead of waiting" syntax Guid task = Triager.StartTask("Review the Lisbon contract."); ``` That opens the agent's task and returns; the declared loop starts on it and runs the agent inside a workflow that can park, escalate and be resumed. The usual shape is to decide which you want first — a cheap classifying `Ask`, then `StartTask` only for the work that warrants it. Name a task type to choose *which* loop runs, when your app declares more than one: ```osy title="naming which loop runs, when there is more than one" syntax Guid task = Triager.StartTask("Review the Lisbon contract."); ``` The loop that tracks that type is the one that starts. The type must be one of yours deriving from `AgentTask`. ## See also {#see-also} - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — what the run cost, what caused it, and how long it took. - [what an agent hands back (AgentDeliverable)](https://osysharp.com/reference/agent/deliverables/) — what the agent hands back beyond a sentence. - [agent conversation memory (using Osysharp.Agents)](https://osysharp.com/reference/agent/conversation-memory/) — turns the platform records for you. - [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) — the workflow a started task runs inside. --- # stopping work (task.Stop) > End a task and everything beneath it, including the model call it is in the middle of. Answers whether a live run was actually interrupted, as opposed to the stop being recorded for work that had not started yet. Who may stop work is who may update the task. ## Summary {#summary} ```osy syntax var interrupted = task.Stop(); ``` Marks the task and everything under it as `Cancelled`, and **trips the model call in flight** so the agent stops now rather than after the answer it was already paying for. ## Signature {#signature} ```osy syntax task.Stop() // → bool — true when a LIVE run was interrupted ``` The return value distinguishes two real outcomes: **stopped** (a run was executing and has been cut off) and **will stop** (nothing was running yet, and the request is remembered so the next run ends immediately). A stop button that conflates them tells the user "done" when the work is still going. ## Description {#description} ### It stops the work, not just the record {#actually-stops} A task can be sitting inside a provider call that takes tens of seconds. `Stop()` cancels it: the call is abandoned, the run unwinds, and nothing further is charged for that turn. The task's row is marked in the same operation, so a [watcher](https://osysharp.com/reference/agent/task-watch/) ends and every list stops showing the task as running. ⚑ Both halves matter. Marking the row alone leaves the agent talking to the model; cancelling alone leaves every screen claiming the work is still in progress. ### Does it stop child tasks too? {#subtree} A task driven by a [loop](https://osysharp.com/reference/agent/loop/) is the parent; the run doing the work is a child. `Stop()` therefore ends the task **and everything beneath it** — stopping only the task you were handed would leave the agent running underneath it. ⚠ Tasks that have already finished are left alone. A child that completed a second before the stop *did* complete, and its record of that is worth more than a uniform status across the tree. ### `Cancelled` is not `Failed` {#cancelled} A stopped task ends as `Cancelled`. That is deliberately distinct from `Failed`: a failure is the work going wrong and worth investigating, a stop is somebody deciding it should not continue. If they shared a state, every operator abort would look like a defect on the one screen you scan for defects. ### Who can stop work {#security} **Stopping is an update.** Declare who may update the task and you have declared who may stop it: ```osy syntax entity ReviewTask : AgentTask { security { allow read when IsAuthenticated; // everyone signed in can WATCH allow update when IsApprover; // …only an approver can STOP } } ``` ⚠ **Read and update are separate on purpose.** Watching work and ending it are different privileges, and an app that lets everyone see a task usually does not mean everyone may kill it. A caller without `update` is refused with a message naming the rule they need. ### What a watcher sees {#watchers} A stop appends a final step, so a [`Watch()`](https://osysharp.com/reference/agent/task-watch/) feed ends with a line saying what happened rather than simply going quiet. A stream that stops producing is otherwise indistinguishable from one that finished normally. ## Examples {#examples} ```osy title="stopping-a-review" test app=agent-task-stop using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity ReviewTask : AgentTask { security { allow read when IsAuthenticated; allow update when IsAuthenticated; } } /// Ends the work and says whether anything was actually interrupted. string StopReview(Guid taskId) { var task = ReviewTask.Where(t => t.Id == taskId).FirstOrDefault(); if (task == null) { return "no such task"; } return task.Stop() ? "stopped" : "nothing was running — it will not start"; } ``` ## See also {#see-also} - [watching a task run (task.Watch)](https://osysharp.com/reference/agent/task-watch/) — following work while it runs, and seeing it end - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — the task itself: what caused it, when it ran, how it finished - [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) — why a task and the run beneath it are two rows --- # the agent loop (app.Agent, Loop) > The workflow an agent's work runs INSIDE. A step of it means "run the agent until it finishes or asks for help" — the workflow supplies durability, the human slot, escalation, retries and the trace, while the agent supplies the turns. Declared once for the app and overridable per agent. Naming a workflow that does not exist is a compile error, because the failure it would otherwise cause is an absence nothing reports. ## Summary {#summary} An agent that answers a question in one turn needs nothing around it. An agent that does **work** — reads several things, calls tools, pauses for a person, resumes hours later — needs everything a workflow already provides. So the work runs inside one, and you say which: ```osy syntax app.Agent = new AgentConfig { Loop = ProcessTask }; // the app default ``` The workflow **wraps** the turn loop; it does not become it. One step of it means *"run the agent until it finishes or asks for help"*. ## Signature {#signature} ```osy syntax app.Agent = new AgentConfig { Loop = // the default loop for every agent in this app }; agent Escalator { Loop = ; // …overridden for this one } ``` Both take a bare workflow NAME. Omit `Loop` on an agent and it takes the app default; omit `app.Agent` too and the agent's work runs with no workflow around it — which is the right answer for an app whose agents only ever answer in the turn. ## Description {#description} ### The workflow supplies the durability, the agent supplies the turns {#boundary} This split is the whole design. The workflow owns: - **durability** — the run survives a restart, a deploy, and hours of waiting; - **the human slot** — when the agent asks a person something, the wait is a modelled fact with an assignee, an opened-at and an SLA clock, not a paused process; - **escalation and retries** — declared, not hand-written; - **the trace** — what happened, in order, queryable afterwards. The agent owns the turns: call the model, dispatch tools, repeat. That loop stays in one place. If a workflow could express it too there would be two implementations of the same thing, and they would drift. ### The loop's subject is the TASK {#subject} A loop workflow runs **over the agent's task** — the same row the work log is built from — and it declares so: ```osy syntax workflow ProcessTask { Tracks = AgentTask.Status; Initial = Running; state Running { } state Waiting { } // parked on a person terminal success Completed { } terminal error Failed { } } ``` Two things follow, and both are the reason for the choice: - **"What has this agent done, or is waiting for" stays one column to list on.** The task's `Status` *is* the workflow's state. A loop with a state of its own would make that two questions, and a list view would have to know which of them to ask. - **The state transition log is the task's.** Every move the loop makes is recorded against the piece of work it is about, so the history is where you would look for it. ⚠ **While a loop drives a task, the workflow OWNS `Status` and nothing else writes it.** The agent's turn loop finishing is not the task finishing — a run parked on a person is still parked, and the task goes on reading `Waiting` until the workflow moves it. What the platform still records directly is what that run *produced*: its outcome and when it stopped. ### What a loop must at least have {#minimum} The platform does not supply the loop. It checks that yours **can do the two things a loop is for**, and refuses at compile time when it cannot: | the rule | why it is a rule | |---|---| | `Tracks = AgentTask.Status` | a loop runs over the agent's own task; tracking something else leaves the task's status written by nothing | | a state for **every** member of `AgentTaskStatus` | a missing member is a state the task can reach and the workflow has nowhere to put | `Waiting` is the one that matters. Without it an agent that asks a person has nowhere to park — and that failure is an **absence**: the work runs, nobody is asked, and there is no exception to catch and no log line to find. Said at compile time it is one sentence naming what to add. Everything else is yours. Who gets notified when the run parks, what the SLA is, how it escalates, how many times it retries — the platform has no opinion, because any opinion it had would be wrong in the apps that disagreed. That is what the `Waiting` state's `enter` body is for. ⚑ **This is also why samples are safe to copy.** Start from one, change it into what your app needs — and if the protocol ever demands more, your copy stops **building** with a sentence naming what to add, rather than quietly going on doing less than it used to. ### Not every task gets one {#which-tasks} - **Work a workflow already drives** needs no second loop — the task points at the run that is already going, and starting a second would put two state machines on one piece of work. - **Work started by a chat message, an event or a schedule** runs in the declared loop, *when the work warrants it*. Opening the task starts the run, bound to that task — so [`.StartTask(trigger)`](https://osysharp.com/reference/agent/ask/) is how a trigger hands work to the loop, and the loop is what runs the agent. - **An agent spawned by another agent** rides its parent's loop; it starts nothing of its own. ⚠ **Do not spin durable machinery for a one-turn answer.** *"What did we spend on travel in Q3"* should cost a model call, not a workflow run. Deciding which is which is your app's job — classify the incoming message first, answer the questions, and start the loop only for the work: ```osy syntax var verdict = Triager.Ask(turns).Text; // cheap: decide whether this is work if (verdict == "work") { juniorLegal.StartTask("…"); // durable: the loop takes it from here } ``` ### Which loop runs is decided by the task's TYPE {#by-type} A loop tracks a task type, and it starts for rows of that type and no other. So an app with more than one kind of agent work declares a task type per kind and a loop per type: ```osy syntax entity PersonalTask : AgentTask { security { allow read when IsAuthenticated; } } workflow PersonalTaskProcessor { Tracks = PersonalTask.Status; Autostart = this.Item.Type != AgentTaskType.Workflow && this.Item.Type != AgentTaskType.Spawn; Initial = Running; state Running { } state Waiting { } terminal success Completed { } terminal error Failed { } } ``` `Autostart` is a plain condition over the task, written directly — the row is in scope as `this.Item`, so there is no lambda to introduce. It is also where *"not every task gets one"* is stated in your own words rather than assumed: a task a workflow already drives, or one an agent spawned, is excluded here. ### A name that resolves to nothing is refused {#refusal} ```text `app.Agent.Loop` names `ProcessTsak`, which is not a declared workflow — add `workflow ProcessTsak { … }`, whose step runs the agent until it finishes or asks for help. Left unresolved the work would run with no workflow around it: no durability, no human slot, no trace, and nothing to say so. ``` This is a compile error rather than a runtime one because **the runtime failure would be an absence**. Nothing throws; the work simply runs bare, and an app that never asked for a loop looks exactly the same. There is no log line to find, because nothing went wrong — something did not happen. The same check covers the per-agent override, which is the same mistake in the other place it can be written. ### The override is on the agent, and the default is resolved at run time {#override} An agent that declares no `Loop` stores none — it is **not** stamped with the app default at compile time. That is deliberate: changing `app.Agent` would otherwise leave every previously-compiled agent pointing at the old workflow. An empty `Loop` means *"ask the app"*, and it is answered each time the work starts. An `agent` declaration seeds a template, and the template carries the `Loop` too — so an instance minted from it later inherits the declaration rather than falling back to the default. ## Examples {#examples} **A real loop, and the reason loops exist.** The agent reviews a claim; when it cannot judge one without the person who filed it, it asks — the run parks in `Waiting`, and their answer hours later resumes the very same run: ```osy title="agent-loop-hitl" test app=agent-loop-hitl using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity Claim { [Required, MaxLength(200)] string Title; [Required] User Filer; security { allow read, create, update when IsAuthenticated; } } /// What the agent asked, and what it was told. The platform parks the run; what the question LOOKS like to the /// person answering it is yours. entity Question { [Required] Claim Claim; [Required] ReviewTask Task; [Required, MaxLength(2000)] string Text; [MaxLength(2000)] string? Answer; security { allow read, create, update when IsAuthenticated; } } entity ReviewTask : AgentTask { security { allow read when IsAuthenticated; } } agent Auditor { Purpose = "Review a claim and recommend approve or send-back."; Prompt = "You review expense claims."; Memory = Persistent; // an agent that retains nothing cannot come back from a park Principal = new User { Email = "auditor@example.com" }; Loop = ReviewClaim; } workflow ReviewClaim { Tracks = ReviewTask.Status; Autostart = true; Initial = Running; event Answered(string text); state Running { enter { var claim = Claim.Where(c => c.Id == this.Item.EntityId).FirstOrDefault(); if (claim == null) { goto Failed; } var turns = new List(); turns.Add(Turn.Context("Claim: " + claim.Title)); turns.Add(Turn.User("Review this claim.")); var reply = Auditor.Ask(turns); if (reply.Parked) { // it stopped to ask a person OpenQuestion(claim, this.Item, reply.Question ?? ""); goto Waiting; } goto Completed; } } state Waiting { enter { Log.Information("waiting on the filer of {Claim}", this.Item.EntityId); } // notifying is yours subscribe Answered(string text) as Filer { Assignee = Claim.Where(c => c.Id == this.Item.EntityId).FirstOrDefault().Filer; Finished { Within = TimeSpan.FromDays(2); Unfinished { goto Failed; } } } on Answered(string text, Slot slot) { var reply = Auditor.Answer(this.Item, text); // their words reach the agent as its question's answer CloseQuestion(this.Item, text); if (reply.Parked) { goto Waiting; } // it asked one more thing — ordinary, not an edge case goto Completed; } } terminal success Completed { } terminal error Failed { Message = "the review could not be completed"; } } void OpenQuestion(Claim claim, ReviewTask task, string text) { var q = new Question { Claim = claim, Task = task, Text = text }; UnitOfWork.Commit(); } void CloseQuestion(ReviewTask task, string text) { var open = Question.Where(q => q.Task == task && q.Answer == null).FirstOrDefault(); if (open != null) { open.Answer = text; UnitOfWork.Commit(); } } /// The trigger. `about:` is what lets the task say which claim it is for. Guid StartReview(Claim claim) { return Auditor.StartTask("claim submitted: " + claim.Title, about: claim); } /// The person's answer, on its way to the parked run. void AnswerAuditor(Question question, string text) { ReviewClaim.For(question.Task).Filer.Answered(text); } ``` Read the three moments in order. `StartReview` opens the task and returns — the submit gesture does not wait for a model. `Running`'s `enter` body runs the agent and **branches on the park** rather than being thrown out of. And `on Answered` hands the person's words back with [`Answer`](https://osysharp.com/reference/agent/hitl/), which is the hop the whole mechanism is for: nothing was suspended, so nothing has to be woken. ⚠ **Everything in `Waiting` is yours.** Who is asked, how they hear about it, how long they get, what happens when they do not reply. The platform's half was making the run parkable at all. A minimal loop, when you only need the wiring — every state present, no body yet: ```osy title="agent-loop-default" test app=agent-loop using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(100)] string DisplayName; security { allow read when IsAuthenticated; allow create when IsAuthenticated || IsAnonymous; } } workflow ProcessTask { Tracks = AgentTask.Status; Initial = Running; state Running { } state Waiting { } terminal success Completed { } terminal error Failed { } } app.Agent = new AgentConfig { Loop = ProcessTask }; agent Triager { Purpose = "Triage incoming tickets."; Prompt = "You triage tickets."; Principal = new User { DisplayName = "Triager" }; } ``` A chat message that turns into work now opens a task, starts a run of `ProcessTask` bound to it, and the task's `Status` reads whatever state that run is in. ⚠ **This one demonstrates the wiring and nothing else** — a reader meeting the feature here would learn that a loop is a two-state workflow and come away with no idea why they would want one. The example above it is the feature. ## See also {#see-also} - [an agent asking a person (the human slot)](https://osysharp.com/reference/agent/hitl/) — the ask-a-human hop in full: what parks a run, and what resumes it - [running an agent from your code](https://osysharp.com/reference/agent/ask/) — running a declared agent from your own code - [Workflow.Work<T> (everything outstanding) and its SLA numbers](https://osysharp.com/reference/workflow/work/) — the human slot the loop gives an agent that needs to ask - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — the task an agent's work opens, and what it records --- # the agent task log (AgentTask) > Every piece of work an agent does is recorded as an `AgentTask` — which agent, what set it going, when it started and finished, and what came of it. Tasks nest: work an agent starts from inside another piece of work becomes a sub-task, so "what did this whole job involve" is one query however many agents it took. The rows are written by the platform and can never be created, edited or deleted by app code; your app decides who may READ them. ## Summary {#summary} You can see what an agent has **said** — that is the conversation. The task log is what it **did**. Each piece of work an agent performs is one `AgentTask` row: whose work it was, what caused it, when it ran, and how it ended. Because agent work sets off more agent work — an agent hands part of a job to another agent, or files a record that starts a process which itself needs an agent — tasks form a **tree**. A task knows its parent and carries its full ancestry, so you can ask about one step or about everything that step led to, at any depth. `AgentTask` arrives with `using Osysharp.Agents;`, alongside the rest of the agent surface. ## Signature {#signature} ```osy syntax using Osysharp.Agents; partial entity AgentTask { security { allow read when IsAuthenticated; } } ``` The fields you will read: | field | what it holds | |---|---| | `Agent` | whose work this was | | `Type` | what set it going — `Workflow`, `Event`, `Schedule`, `Chat`, or `Spawn` (another agent's task) | | `Status` | `Running`, `Completed` or `Failed` | | `Title` · `Trigger` | one line for a list; the full reason it ran | | `Parent` · `Children` · `Path` · `RootTask` | the tree — see below | | `StartedAt` · `CompletedAt` · `Outcome` | when, and how it ended | | `WorkflowRun` · `ChatSession` | the process or conversation it belongs to, when it belongs to one | | `EntityTypeName` · `EntityId` | the record it is about, when it is about one | | `Principal` · `OnBehalfOf` | who it ran as, and whose behalf it ran on | Cost is **not** a field — see below. ## Description {#description} **The organising unit is the AGENT, not the process.** The question the log answers is *"what has this agent done"* — a list of its recent work with its type, its timing and its outcome. A business process is one of the things that can cause agent work; plenty of processes never involve an agent at all, and those create nothing here. **Not every agent turn is work.** A question the agent answers there and then — *"what did we spend on travel in Q3?"* — is a conversation, not a job, and it writes no task. A task exists when something set the agent to WORK: a process step, an event, a schedule, a request that turned into a piece of work, or another agent handing part of a job over. That is deliberate: a log that recorded every exchange would bury the work in chatter. **Tasks nest, across mechanisms.** An agent's work can create a record that starts a process, whose step needs agent work, whose agent hands part of the job to another agent. Each of those is a sub-task of the one before it, and the chain is recorded the same way regardless of what made each hop. A **sub-task means the work went to a different actor** — another agent, or a person — not that the same agent moved on to its next step. **`Path` is what makes "and everything it led to" cheap.** Every task carries its ancestry as a path ending in its own id, so one filter selects a task together with all its descendants, however deep. Reading `Children` gives you the immediate sub-tasks; matching on `Path` gives you the whole subtree. **Cost is not a field either, and that is the same decision.** Every model call the task caused is recorded with the task's id and its path, so *"what did this cost"* is a sum over those calls, and *"what did this cost all in"* is a sum over every call whose path starts with this task's. Both are exactly the sum of the calls they summarise — a stored total can disagree with its own calls after a run that failed half-way, with nothing to reconcile it against. The calls are `LlmCallRecord` rows, which your app can already query. `AgentTask` is the task each call belongs to, `TaskPath` is that task's ancestry, and the same aggregate over `InputTokens`/`OutputTokens` gives tokens instead of money. ⚑ **It counts what the agent's TOOLS spent, not just its own turns.** A tool that runs an extraction or a classification is doing model work the task caused, and it lands under the same task without anyone passing anything — because the attribution happens where every model call goes through, not where turns are counted. **Waiting is not recorded here.** A task that is waiting for a person is waiting inside a process, which already records who it was assigned to, when it opened, when they picked it up and whether it ran late. The task points at that process rather than keeping a second copy of the same clock — two copies of one fact drift the day somebody fixes one of them. **The rows are written by the platform.** App code can never create, change or delete an `AgentTask`: a fabricated row would attribute work to an agent that never did it, and a deleted one would hide work that happened. Attempting a write is refused. **Who may READ them is entirely yours.** The platform ships no opinion about that, which means a plain `using Osysharp.Agents;` gives you a table nobody can read yet. Declare the rule you want, the same way you would for any other entity — everyone signed in, only managers, only the person the work was done for. Building the queue screen, the review list and the activity dashboard is your app's job too; the log is the material they are built from. ## Examples {#examples} An app that lets any signed-in person see the agent work log: ```osy title="agent-task-log-read-rule" test app=agent-task-log using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } partial entity AgentTask { security { allow read when IsAuthenticated; } } ``` With that in place, "what has this agent been doing" is an ordinary query over an ordinary entity — and so is "show me everything that came out of this one job", by matching descendants on their `Path`. ## See also {#see-also} - [what an agent hands back (AgentDeliverable)](https://osysharp.com/reference/agent/deliverables/) — what the work PRODUCED: the documents, files and records the agent hands back. - [agent conversation memory (using Osysharp.Agents)](https://osysharp.com/reference/agent/conversation-memory/) — what the agent SAID, as against what it did. - [running an agent from your code](https://osysharp.com/reference/agent/ask/) — running an agent from your own code. --- # turning AI off (the runtime switch) > An operator can switch an application's AI off while it runs — no recompile, no redeploy. Text generation and embedding are two independent switches, because they do different things and send different data. A refused call fails with a 403 naming which capability was off; it never silently returns nothing. ## Summary {#summary} Every AI call an application makes passes through one place, and an operator can close it. Two switches, not one: **text generation** and **embedding** are turned off independently. Neither needs a recompile, a redeploy or a restart — the change reaches every process within about fifteen seconds. A call made while its capability is off does not quietly return nothing. It fails, with a message naming which capability was switched off and noting that the other is switched separately. ## Signature {#signature} ```text app-detail → AI ▢ Text generation — models may write for this app ▢ Embedding — semantic search, and every indexed row is sent to the model host ``` There is no Osy# declaration for this. It is deliberately not something an application can write about itself — see [Who can change it](#who). ## Description {#description} ### Why two switches and not one {#two} They differ on both axes that matter to whoever is turning AI off. **What they do.** Generation samples text that influences something a person reads or acts on. An embedding is a single forward pass producing a fixed-size vector: it *ranks*, it does not decide or write prose. It is still inference — calling it "not AI" would not survive a compliance reading — but it is not what a rule about AI in decisions is aimed at. **What they send.** This is the one that catches people out. A generation call sends what somebody typed. Embedding sends **every indexed row** to whoever hosts the model — much the larger flow of application data leaving the platform. So a policy about *generated output* covers only the first, while a policy about *where data may go* covers both. Because only you know which policy you are applying, the platform models the two and composes neither. If you want one "AI off" control, turn both off. > ⛔ **"AI is off" is false while either one runs.** Turning generation off and reporting "we disabled AI" is a > statement about data egress that is not true if embedding is still running. Both the admin page and the refusal > message say which capability is which for exactly this reason. ### Who can change it {#who} The application's own **Owner or Admin**, its organization's **Owner or Admin**, or a platform admin. It is stored in the control plane, not in the application's model, and that placement is the point: an operator's decision must not be something the application's own source can withdraw at its next compile. It is also the only field pair on an application record that an app's own Owner may write — everything else there stays with the organization tier. The reasoning: this is not administration of the app record, it is an operational pull on what the app *does*, and the person accountable for that must be able to stop it without escalating. ### What a refused call looks like {#refused} The call fails. Over HTTP the response is **403** with the message: ```json title="generation switched off" syntax { "error": "Text generation is switched off for this application — an operator disabled the Generative AI capability, so no model call was made. This is not a budget limit and will not clear on its own. Embedding (semantic search) is switched separately and may still be running." } ``` 403 rather than 500, because this is a decision somebody made rather than a fault; and rather than 429, because a budget refusal clears at midnight and invites a retry while this one does not clear at all. ### When it takes effect {#timing} Within about **fifteen seconds**, in every process. The switch is read on every AI call, so it is cached briefly rather than re-read from the control plane each time; the cache is time-bounded, so a change propagates everywhere with nothing to deliver and nothing to go wrong in delivering it. So "it is off" and "it will be off shortly" are different claims for a few seconds after you flip it. The admin page says so. ### What it does NOT do {#limits} Two things worth knowing before you design around this. **An application CAN ask whether AI is on** — `Ai.GenerationEnabled` and `Ai.EmbeddingEnabled`, two booleans read on the server: ```osy title="hide the affordance instead of failing on it" test app=agent-ai-switch-hide using Osysharp.Ui; [Page("/assistant")] [Render(CSR)] [AllowAnonymous] component Assistant() { live var aiOn = Ai.GenerationEnabled; render { if (aiOn) { Text("Ask the assistant anything."); } else { Text("The assistant is switched off for this application."); } } } ``` ⛔ **This is advisory, never a gate.** The authority is the refusal above: the read has crossed to a client and can be up to fifteen seconds stale, so a page that hides a button is being polite, not enforcing anything. What makes the pair trustworthy is that both read the same switch — the button and the refusal cannot disagree about the answer, only about how fresh it is. ⚠ And it is read when the page loads, not pushed. A page already open when the switch is flipped keeps showing the button until it reloads; pressing it then gives the refusal. If you need the page to react live, that is a different mechanism. **The refusal is not a catchable Osy# exception.** It is not a member of the language's closed exception set, so `catch (…)` in Osy# cannot name it specifically. It surfaces as a call failure carrying the message above. **Rows already embedded were already sent.** Turning embedding off stops future calls; it does not recall anything. If the concern is where data has gone rather than where it is going, this switch is not the whole answer — see [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) for running the model somewhere you choose instead. ## Examples {#examples} An operator turns generation off for one application and leaves search working: ```text title="one capability off, the other left running" app-detail → AI ▢ Text generation ← unticked ☑ Embedding "Generation is off. Embedding still runs, so indexed rows are still sent to whoever hosts that model." ``` The application's next model call fails with the 403 above. Its semantic search keeps answering. ### The dial beside the switch {#budget} The switch is binary. The [budget](https://osysharp.com/reference/agent/llm-budget/) is the same control plane's dial: hard daily limits in tokens and dollars, per organisation, per application and per user, enforced before a call leaves and fail-closed. An application that handles the switch's refusal handles the budget's the same way — both are the model not answering, and the degraded path is one path. ## See also {#see-also} - [LLM budgets (hard daily limits per organisation, app and user)](https://osysharp.com/reference/agent/llm-budget/) — the dial beside this switch: hard daily budgets per organisation, app and user - [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — the model that is being switched off, and where it runs - [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) — the embedding model, its endpoint, and why placement is a requirement rather than a preference - [Agents (calling a model like anything else you declared)](https://osysharp.com/reference/agent/index/) — the rest of the agent and model surface --- # watching a task run (task.Watch) > Everything a task has done so far, then everything it does next, as one stream that ends when the task does. A watcher can arrive late, leave, and come back — the work is driven by the task, not by whoever is looking at it, so watching costs the task nothing and stopping watching costs it nothing either. ## Summary {#summary} ```osy syntax foreach (var step in task.Watch()) { // step.Text — "Using Search", "recommending approval" } ``` One `foreach`. It replays what already happened, keeps going as more happens, and finishes when the task reaches a terminal state. **Arriving late is not a special case** — a watcher who opens a task halfway through sees the same thing as one who was there from the start. ## Signature {#signature} ```osy syntax task.Watch() // → stream ``` | `AgentStep` | | |---|---| | `Sequence` | order within the whole job, from 1 | | `Kind` | `Said` · `ToolCall` · `ToolResult` · `Asked` · `Answered` · `Finished` | | `Text` | the line a progress view shows | | `Detail` | the tool name, the terminal state, the failure | | `IsError` | the tool failed (`ToolResult` only) | | `At` | when it happened | ⚠ It is a **method, not a property** — the parens are carrying meaning. [`task.Calls`](https://osysharp.com/reference/agent/task-calls/) is a *value*, complete when you get it; this opens something with a lifetime. ## Description {#description} ### Watching is free, and so is looking away {#detach} The task's work is driven by its [loop](https://osysharp.com/reference/agent/loop/), not by you. So: - **open it** and you see everything so far, then everything next; - **close it** and the task carries on exactly as before; - **come back** and call `Watch()` again — it catches you up. There is no cursor to keep, no reconnect to write, and no state on the client at all. That is the whole reason this is a single member rather than a history call plus a live subscription: the moment they are two, every caller has to join them, and get the join right. ⚑ A watcher must live inside something that can pass items on as they arrive — so a function reading a stream is itself declared `stream`. The compiler enforces this, which is what stops a watcher being written as an ordinary function that quietly blocks until the task ends. ```osy syntax stream Progress(Guid taskId) { var task = ReviewTask.Where(t => t.Id == taskId).FirstOrDefault(); foreach (var step in task.Watch()) { yield return step.Text; } } ``` ### Does it cover child tasks too? {#subtree} A task driven by a loop makes no model call itself — the run it starts is a child task, and the work is recorded against the child. `Watch()` therefore covers the task **and everything beneath it**, which is what makes it show anything at all on the task you were handed. Same reason [[agent-task-calls#allcalls|`AllCalls`]] exists. ### It ends when the task ends {#terminal} Completed, failed, or [stopped](https://osysharp.com/reference/agent/task-stop/) — the stream finishes and the `foreach` exits. A task that is `Waiting` on a person is **not** terminal and the stream stays open: that is the case a watcher most wants to be attached for, because the thing being waited on is usually them. ### Who can read it {#security} **If you can read the task, you can read its progress.** Steps hang off the task, so there is no second rule to declare and none to forget: ```osy syntax partial entity AgentTask { security { allow read when IsAuthenticated; } } ``` ⚠ A step says what the agent **did** — "Using Search", "recommending approval". It never carries what a tool returned, because a tool result is the agent's own read performed with the *agent's* authority. That is [`task.Transcript`](https://osysharp.com/reference/agent/task-transcript/), behind its own gate. ## Examples {#examples} ```osy title="watching-a-review" test app=agent-task-watch using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity ReviewTask : AgentTask { security { allow read, update when IsAuthenticated; } } /// A progress feed a screen can bind straight to. stream Progress(Guid taskId) { var task = ReviewTask.Where(t => t.Id == taskId).FirstOrDefault(); foreach (var step in task.Watch()) { yield return step.Sequence.ToString() + ". " + step.Text; } } ``` ## See also {#see-also} - [stopping work (task.Stop)](https://osysharp.com/reference/agent/task-stop/) — ending work that is still running, including the model call it is in - [what a task cost, and what it did (task.Calls)](https://osysharp.com/reference/agent/task-calls/) — what the same work *cost* - [what the agent saw (task.Transcript)](https://osysharp.com/reference/agent/task-transcript/) — what the agent actually read and wrote, behind its own gate --- # what a task cost, and what it did (task.Calls) > Every model call an agent task paid for, read off the task itself — the model, the turn, the tokens, the cache hits, the cost, how long it took, and whether it failed. `Calls` is what that one step spent; `AllCalls` is what the whole job spent, including the work it set off. Totals are ordinary LINQ over the list, so there is no stored number to drift from the rows it summarises. ## Summary {#summary} A task tells you an agent did some work. This tells you what that work *cost* and what it consisted of. ```osy syntax var spend = task.AllCalls.Sum(c => c.Cost); // what the whole job cost var slow = task.AllCalls.Where(c => c.DurationMs > 5000); var broke = task.AllCalls.Where(c => c.Error != null); ``` Each entry is one call to a model. Because the cost is **on each call**, every total you might want is a `Sum` you write yourself — there is no stored figure that could disagree with the calls behind it. ## Signature {#signature} ```osy syntax task.Calls // → List this task's own calls task.AllCalls // → List this task and everything beneath it ``` | `AgentLlmCall` | | |---|---| | `Model` | the model that answered — the tier actually used, not the one declared | | `Turn` | which turn of the run this was (1-based) | | `InputTokens` · `OutputTokens` | tokens sent and generated | | `CacheCreationTokens` · `CacheReadTokens` | cache written, and cache read — reads are the ones that save money | | `Cost` | what this call cost, in your currency units, as a `decimal` | | `DurationMs` | wall-clock time for the provider call | | `Truncated` | the model hit its token ceiling and was cut off mid-answer | | `Error` | the failure, or null. A task whose calls carry errors spent money without delivering | | `At` | when the request went out | | `Task` | which task in the subtree made the call — so a total can be broken down by step | ## Description {#description} ### `AllCalls` is almost always the one you want {#allcalls} ⚠ **A task driven by a [loop](https://osysharp.com/reference/agent/loop/) makes no model calls itself.** The loop's task is the parent; the agent run it starts is a child task, and the calls are recorded against the *child*. So on a loop-driven task: ```osy syntax task.Calls.Sum(c => c.Cost) // 0.00 — the parent spent nothing task.AllCalls.Sum(c => c.Cost) // what the job actually cost ``` That is why they are two members rather than one with a flag: a reader must not have to work out which they are holding. Reach for `Calls` when you specifically want *this step's* spend and not its children's. ### The totals are yours to write {#totals} There is no `task.Cost`. The task deliberately stores no total, because a stored number and the rows it summarises disagree the first time something fails halfway — and then nothing can say which is right. Summing the calls cannot drift, and it gives you every other question for free: ```osy syntax var spend = task.AllCalls.Sum(c => c.Cost); var turns = task.AllCalls.Count; var cached = task.AllCalls.Sum(c => c.CacheReadTokens); var priciest = task.AllCalls.OrderByDescending(c => c.Cost).FirstOrDefault(); ``` ⚑ Cost is converted once from the platform's internal whole-number units, so summing a list of these is exact. A per-call rounded figure would not be. ### Who can read it {#security} **If you can read the task, you can read its calls.** There is no second rule to declare and none to forget: you can only ask about a task you are holding, and you could only be holding one your app's own rule on [`AgentTask`](https://osysharp.com/reference/agent/task-log/) allowed you. So the decision is the one you already made: ```osy syntax partial entity AgentTask { security { allow read when IsFinance; } // …and only finance sees what anything cost } ``` ⚠ **Prompts and responses are NOT here.** These entries say what a call *cost*, never what it *contained*. That is deliberate: an agent often runs with more authority than the person reading the screen, so its prompts can hold data that reader is not entitled to. Exposing content through the same member as cost would make one read rule the only thing standing between them. Content is [`task.Transcript`](https://osysharp.com/reference/agent/task-transcript/), behind a gate the agent declares for itself. ## Examples {#examples} A review screen — the spend, and the calls behind it: ```osy title="what-a-task-cost" test app=agent-task-calls using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity ReviewTask : AgentTask { security { allow read when IsAuthenticated; } } /// What one task spent, and what it did to spend it. string Spend(Guid taskId) { var task = ReviewTask.Where(t => t.Id == taskId).FirstOrDefault(); if (task == null) { return "no such task"; } var calls = task.AllCalls; var cost = calls.Sum(c => c.Cost); var failed = calls.Where(c => c.Error != null).Count(); return calls.Count.ToString() + " calls, " + cost.ToString("C") + (failed > 0 ? " (" + failed.ToString() + " failed)" : ""); } ``` ## See also {#see-also} - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — the task itself: what caused it, when it ran, how it ended - [what an agent hands back (AgentDeliverable)](https://osysharp.com/reference/agent/deliverables/) — what the agent chose to hand back, as opposed to what it spent - [what the agent saw (task.Transcript)](https://osysharp.com/reference/agent/task-transcript/) — what those calls *contained*, and who may read it - [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) — why a loop-driven task's own calls are empty --- # what an agent hands back (AgentDeliverable) > An agent presents its outcome as a LIST of deliverables, not a sentence: documents it wrote, files it produced, and records it created, in the order it chose. It records each one deliberately, by calling a tool for it, so the list is what the agent means to hand over rather than everything it happened to touch. The rows are written by the platform and can never be created, edited or deleted by app code; your app decides who may READ them, and builds the screens that show them. ## Summary {#summary} A task's `Outcome` is one sentence — enough for a list view, and never enough to act on. The deliverables are what the sentence is about. Each thing an agent hands back is one `AgentDeliverable` row hanging off its task: a **document** it wrote, a **file** it produced, or a **record** it created. A task has as many as it needs, in the order the agent chose, and the three shapes sit in one list — so a screen can show a summary, the memo behind it and the twelve receipts that were filed, together. `AgentDeliverable` arrives with `using Osysharp.Agents;`, alongside [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/). ## Signature {#signature} ```osy syntax using Osysharp.Agents; partial entity AgentDeliverable { security { allow read when IsAuthenticated; } } ``` The fields you will read: | field | what it holds | |---|---| | `Task` | the work this is an outcome of | | `Kind` | `Document`, `File` or `Record` — which of the three below carries the content | | `Sequence` | the agent's own ordering, from 0 | | `Label` | what this IS, in a few words — the line a reviewer scans, and what groups related rows | | `Document` | `Kind = Document`: the markdown the agent wrote | | `FileAsset` | `Kind = File`: the file it produced | | `EntityTypeName` · `EntityId` | `Kind = Record`: the record it created | And from the other side, on the task itself: | field | what it holds | |---|---| | `AgentTask.Deliverables` | every outcome of that task, as a collection | ## Description {#description} **A list, because a sentence cannot carry an answer.** *"Checked the report and filed one receipt"* tells a reviewer nothing they can open. The deliverables are the openable half: the policy check they can read, the memo they can download, the draft they can approve. **One row per thing, and grouping is yours.** Twelve filed receipts are twelve rows sharing a `Label`, not one row that mentions twelve. A list can always be grouped for display; a group cannot be ungrouped, and the individual rows are what a reviewer clicks. **The agent records these DELIBERATELY, and that is what makes the list worth reading.** The platform separately knows everything a task touched — that is the audit trail, and it is complete. This list is different: it holds only what the agent chose to present. Most rows an agent touches on the way to an answer are working material, and a list derived from them would bury the answer in bookkeeping. ⚑ **So an agent that does the work and presents nothing leaves an empty list**, and that is a finding worth showing rather than an error. It means the work happened and nobody can see what came of it. The platform will not refuse to finish such a task — an agent whose honest answer is "nothing to report" has to be able to say so. **A document is markdown, and that buys more than formatting.** It is stored as a real document with sections, so it can be read section by section, edited afterwards, and — because it is indexed for recall — found later by what it SAYS. *"What did we decide about the Lisbon policy"* can find the deliverable that decided it, months on. A plain string would be a dead end in exactly the place it is most useful. **A deliverable never points at nothing.** Recording a record or a file that does not exist is refused at the moment the agent tries, while the agent is still working and can fix it — rather than becoming a card on a review screen that looks live and opens nothing. **The rows are written by the platform.** App code can never create, change or delete an `AgentDeliverable`: a fabricated one would claim an agent produced something it did not, and a deleted one would hide what it did produce. Attempting a write is refused. **Who may READ them is entirely yours**, exactly as for the task log — a plain `using Osysharp.Agents;` gives you a table nobody can read yet, and you declare the rule you want. The review screen, the approval queue and the activity dashboard are your app's to build; these rows are the material. ## Examples {#examples} An app that lets any signed-in person read agent work and everything it produced: ```osy title="agent-deliverables-read-rule" test app=agent-deliverables using Osysharp.Agents; [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } partial entity AgentTask { security { allow read when IsAuthenticated; } } partial entity AgentDeliverable { security { allow read when IsAuthenticated; } } ``` With both rules in place, a task's outcomes are an ordinary collection on an ordinary entity: read `task.Deliverables`, order by `Sequence`, and render each row by its `Kind`. ## See also {#see-also} - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — the work itself: what caused it, when it ran, what it cost. - [agent conversation memory (using Osysharp.Agents)](https://osysharp.com/reference/agent/conversation-memory/) — what the agent SAID, as against what it handed over. - [running an agent from your code](https://osysharp.com/reference/agent/ask/) — running an agent from your own code. --- # what the agent saw (task.Transcript) > What an agent's model calls actually contained — the system prompt as the model received it, the messages sent, the response that came back, and every tool the turn invoked with its input and output. Unlike a task's costs, content is not readable just because you can read the task: the agent declares who may see what it saw, and an agent that declares nobody is readable by nobody. ## Summary {#summary} [`task.Calls`](https://osysharp.com/reference/agent/task-calls/) tells you what a task *cost*. This tells you what it *contained*. ```osy syntax foreach (var turn in task.Transcript) { Log.Information("turn {N}: {Response}", turn.Turn, turn.Response); } ``` ⛔ **This is the one agent surface with a gate of its own**, and it is worth knowing why before you use it. An agent usually runs with **more authority than the person reading the screen** — an auditing agent may read every line of every report, while the employee looking at the task may read only their own. Everything the agent read is in its prompt. So content does not ride the task's read rule; the agent says who may see it, and says it by default to nobody. ## Signature {#signature} ```osy syntax task.Transcript // → List ``` | `AgentLlmTurn` | | |---|---| | `Turn` | which turn of the run this was (1-based) — pairs with `AgentLlmCall.Turn` | | `Model` | the model that answered | | `SystemPrompt` | the instructions **as the model received them**, after every interpolation | | `Messages` | the messages sent, as JSON text | | `Response` | what came back — text and tool requests, in the order the model produced them, as JSON text | | `At` | when the request went out | | `ContentWithheld` | the app chose not to record this turn's content — see [[agent-task-transcript#withheld|when the content was never recorded]] | | `Tools` | what this turn invoked, in order. Empty on a turn that only talked | | `AgentToolCall` | | |---|---| | `Name` | the tool as the model named it | | `Input` | the arguments the model generated, as JSON text | | `Output` | what the tool returned to the model, as JSON text | | `IsError` | the tool failed | | `DurationMs` | wall-clock time for the tool itself | | `Sequence` | order within the turn (1-based) | ## Description {#description} ### Who can read it — you must say, or nobody can {#security} Say it on the agent, in its `security { }` block: ```osy syntax agent Auditor { Prompt = "You review expense reports…"; Roles = [Role.Finance]; // what makes its prompts finance-scoped security { allow read Transcript when IsFinance; } // who may read what it saw } ``` **Omit the rule and the transcript is unreadable — by everyone, including the roles the agent itself holds.** That is deliberate. A gate that defaulted to "readable" would make forgetting the rule indistinguishable from deciding you did not need one, on the one surface where those must not look alike. The rule is written on the *agent* rather than on [`AgentTask`](https://osysharp.com/reference/agent/task-log/) because the exposure belongs to the agent: `Roles = [Role.Finance]` is the line that puts finance-scoped data into its prompts, and the gate sits three lines below it. Two agents in the same app can hold very different authority, and a single app-wide switch would have to be as strict as the most privileged one — or leak through the loosest. ⚠ Its predicate is about the **caller**, so it takes `when`, not `where`. Name a policy (`when IsFinance`) or write the condition inline; there is no row to filter. ### Does it include child tasks' turns? {#subtree} `Transcript` includes the turns of everything the task set off, not just its own — because a task driven by a [loop](https://osysharp.com/reference/agent/loop/) makes no model call itself, so "its own" would be empty for exactly the tasks you most want to inspect. This is the same reason [[agent-task-calls#allcalls|`AllCalls`]] exists, which is why there is no `AllTranscript` to choose between. ⛔ **If any agent involved refuses you, you get nothing at all** — not the turns you would have been allowed. A transcript with some turns quietly missing cannot be told apart from an agent that simply said little, and a reader would have no way to know they were looking at a partial record. Where a job spans agents with different gates, that means you need clearance from each. ### When the content was never recorded {#withheld} A turn whose `ContentWithheld` is true happened and cost what [its call](https://osysharp.com/reference/agent/task-calls/) says it cost, but its prompt and response were never written down. Three things cause it: - the agent declares `Logging = MetadataOnly`; - the app turned the call record off entirely; - the platform dropped the body because it carried data at a redacted classification. Show it. A blank prompt with no explanation reads as a broken screen: ```osy syntax foreach (var turn in task.Transcript) { if (turn.ContentWithheld) { /* "not recorded" */ } else { /* turn.SystemPrompt, turn.Messages, turn.Response */ } } ``` ## Examples {#examples} A review screen showing what the agent was told and what it did about it: ```osy title="what-the-agent-saw" test app=agent-task-transcript using Osysharp.Agents; [Role] enum Role { Finance, Staff } [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity RoleGrant { [Required] User User; [Required] Role Role; security { allow read when IsAuthenticated; } } policy IsFinance => RoleGrant.Any(g => g.User == user && g.Role == Role.Finance); /// Anyone signed in may see that the review happened, and what it cost. entity ReviewTask : AgentTask { security { allow read when IsAuthenticated; } } agent Auditor { Purpose = "Review a submitted expense report."; Prompt = "You review expense reports against the travel policy."; Principal = new User { Email = "auditor@ledger.demo" }; Roles = [Role.Finance]; /// …but only finance sees what it read to do so. security { allow read Transcript when IsFinance; } } /// What the agent was told, and which tools it reached for. string WhatItSaw(Guid taskId) { var task = ReviewTask.Where(t => t.Id == taskId).FirstOrDefault(); if (task == null) { return "no such task"; } var turns = task.Transcript; if (turns.Count == 0) { return "not available to you"; } var tools = 0; foreach (var turn in turns) { tools = tools + turn.Tools.Count; } return turns.Count.ToString() + " turns, " + tools.ToString() + " tool calls"; } ``` ## See also {#see-also} - [what a task cost, and what it did (task.Calls)](https://osysharp.com/reference/agent/task-calls/) — what the same calls *cost*, readable by anyone who can read the task - [the agent task log (AgentTask)](https://osysharp.com/reference/agent/task-log/) — the task itself: what caused it, when it ran, how it ended - [the agent loop (app.Agent, Loop)](https://osysharp.com/reference/agent/loop/) — why a loop-driven task's own calls are empty, and this member spans the job --- # publishing a REST API (app.Apis) > `app.Apis` publishes your app to a third party over HTTP. You never write a controller or an endpoint handler — you EXPOSE what already exists: `Expose` turns an entity into CRUD routes (`new Crud() { Operations = [...] }`), and `Endpoints` maps one of your functions to a route (`new Endpoint(SubmitOrder) { Method = HttpMethod.Post, Path = "/submit" }`). Each `RestApi` has a `Route` prefix and an optional `Auth` (API key and/or bearer). The entity in a `Crud` and the function in an `Endpoint(...)` must exist — a name that doesn't resolve is a compile error that names what does. ## Summary {#summary} `app.Apis` publishes your application over HTTP for other systems to call. The guiding idea is that you **expose what you already have** rather than write a web layer: you do not author controllers, routes, DTOs or handlers. Two things can be published — an **entity**, as a set of CRUD routes, and a **function**, mapped to a single route. Each API has a `Route` prefix and an optional `Auth` gate. ```osy syntax app.Apis = [ new RestApi("Orders") { Route = "orders", Auth = new ApiAuth { ApiKey = true }, Expose = [ new Crud() { Operations = [CrudOp.Read, CrudOp.Create] } ], Endpoints = [ new Endpoint(SubmitOrder) { Method = HttpMethod.Post, Path = "/submit" } ], }, ]; ``` ## Signature {#signature} ```osy syntax app.Apis = [ new RestApi("Name") { // one entry per published API Route = "orders", // the URL prefix for every route below Version = "1.0", // optional — omit and it defaults to v1 Auth = new ApiAuth { ApiKey = true, Bearer = true }, // optional gate Expose = [ // entities → CRUD routes new Crud() { Operations = [CrudOp.Read, CrudOp.Create, CrudOp.Update, CrudOp.Delete] }, ], Endpoints = [ // functions → one route each new Endpoint(SubmitOrder) { Method = HttpMethod.Post, Path = "/submit", SuccessStatus = 201 }, ], }, ]; ``` `app.Apis` is a list — an app may publish several independent APIs, each with its own `Route` and `Auth`. ## Description {#description} A `RestApi` has: - **`Route`** — the URL prefix under which its routes live. - **`Version`**, **`Deprecated`**, **`Sunset`** *(optional)* — API lifecycle metadata. Every route lives under a `/v{major}/` prefix; an omitted `Version` defaults to **v1**, so the simple case needs no version at all. A multi-major API gives each `RestApi` its own `Version` (e.g. `"1.0"`, `"2.0"`). - **`Auth`** *(optional)* — an `ApiAuth { ApiKey = true, Bearer = true, OAuth = true }`. Those three flags are its WHOLE vocabulary; it names no secret and takes no other member. Absent, the API is unauthenticated. Who each of them makes the caller is the next section — read it before you write a `security {}` rule for an API. - **`Expose`** — a list of `new Crud() { Operations = [CrudOp.…] }`. Each entry turns one entity into REST routes; `Operations` chooses which of `Read` / `Create` / `Update` / `Delete` exist. The entity must be defined in your app — a `Crud` is a compile error that lists the entities you *do* define. - **`Endpoints`** — a list of `new Endpoint(Function) { Method = HttpMethod.…, Path = "…" }`. Each maps one of your functions to a route. The function must be declared — an `Endpoint(NoSuchFn)` is a compile error that lists your functions. You write no request parsing, no serialization, and no routing table: the shape of the entity and the signature of the function are the contract. **Refusals map to the right status.** When an endpoint's function *refuses* — it `throw`s a typed exception, or a declared security policy denies the caller — the response carries the matching 4xx, not a blanket 500, and the client sees the refusal's own message: | The function… | Response | |---|---| | `throw new ValidationException("…")` | `400` — the request was invalid | | `throw new NotFoundException("…")` | `404` — the target does not exist / is not visible | | `throw new ConflictException("…")` | `409` — conflicts with current state | | is denied by a security / authorization policy | `403` — the caller may not do this | | hits a genuine, unexpected error | `500` — a generic message; the details stay in the server log, never the response | So a business rule like *"a backup can only be downloaded once it is ready"* is a `throw new ValidationException(…)` that reaches the caller as a `400` with your wording — not a server crash. ### What a value looks like on the wire {#wire-form} JSON has no literal for most of what your entities hold, so each type has one agreed spelling — the same one going out as coming in, which is what makes a response postable straight back: | Declared as | On the wire | |---|---| | `enum` | its **member name** — `"machine": "Washer"`, never the ordinal `0` | | `enum` with `[Value("…")]` | that **value**, because you chose it — `"risk": "risk-high"` | | `Guid`, `DateTime`, `DateOnly`, `TimeOnly`, `TimeSpan` | a string in the canonical form — `"2026-09-04"`, `"01:30:00"` | | `int`, `decimal`, `bool` | the JSON number or boolean, unquoted | **An enum also accepts its stored key inbound** — the ordinal, or the `[Value]` of a string-backed enum — so a client written against an older payload keeps working. The name is what a read ANSWERS and what the published OpenAPI advertises; the key is a compatibility affordance. Anything else is a **`400` naming the field and what it accepts**, with an enum's whole closed set spelled out: ```json title="a value outside the vocabulary" syntax { "error": { "code": "VALIDATION_FAILED", "details": [ { "field": "machine", "code": "INVALID_ENUM_VALUE", "message": "'machine' expects one of Machine: Washer, Dryer — received a string ('Toaster')." } ] } } ``` ### …and what the response is WRAPPED in {#envelope} The table above is about one VALUE. This is about the **object it arrives inside**, which is not always the value itself — and every key in it is **camelCase**, whatever the member is called in your source. | The route | What comes back | |---|---| | an `Endpoint` whose function returns an **entity** | that row, **flat** — `{"id": "…", "accession": "ACC-1"}` | | an `Endpoint` whose function returns a **`class`** | its fields, **flat** — `{"accession": "ACC-1", "species": "Rana"}` | | an `Endpoint` whose function returns **`void`** | `{"status": "ok"}` | | an `Endpoint` whose function returns **anything else** — a `List`, a `Dictionary`, an `int`, a `string` | **wrapped**: `{"result": …}` | | `Crud` **read-many** (`GET /entities/T`) | `{"items": [ … ], "total": 12, "top": 50, "skip": 0, "hasMore": false}` — plus `"included"` when you asked to expand | | `Crud` **read-one / create / update** | that row, **flat** | | `Crud` **delete** | `204`, no body | ⚠ **The `result` wrapper is the one that catches people, because the obvious DTO is the one that does not work.** A route whose function returns `List` does **not** answer a bare JSON array, so `JsonSerializer.Deserialize>(body)` fails — the body is an object. Declare the wrapper instead, and read through it: ```osy syntax class ReceiptPage { public List Result; } // `Result` binds the body's `result` var page = JsonSerializer.Deserialize(r.Body); Assert.Equal(2, page.Result.Count); ``` [Calling your own REST API from a test](https://osysharp.com/reference/testing/api-calls/) has this as a compiled example, and [JsonSerializer](https://osysharp.com/reference/json/serializer/) is the verb that reads it. ## Who is `user`? {#who-is-user} Every rule you already wrote applies to an API call unchanged, because an authenticated API caller is **a user of your app** — not a special anonymous "machine" identity. This is the one thing about `app.Apis` worth reading before you design anything: guessing it the other way leads you to open your entities to anonymous callers so the API "works", which opens them to the whole world on every other surface too. **An API key is a PER-USER credential. There is no app-wide API key.** A key is minted against exactly one `[Principal]` row, and a request carrying it runs **as that user**: | `Auth` | the request carries | `user` | `IsAuthenticated` | `IsAnonymous` | |---|---|---|---|---| | `new ApiAuth { ApiKey = true }` | `X-API-Key: pk_…` | the key OWNER's principal row | `true` | `false` | | `new ApiAuth { Bearer = true }` | `Authorization: Bearer …` | that token's principal row | `true` | `false` | | `new ApiAuth { OAuth = true }` | an OAuth-issued bearer token | that token's principal row | `true` | `false` | | any `Auth` at all | *nothing* | — | — | — → the request is **`401`** and never reaches your data | | **no `Auth`** | anything | `null` | `false` | `true` | So an API key and a bearer token for the same person produce **the same context**: the same `user`, the same role grants, the same row filters. A rule like `allow read where OwnerEmail == user.Email` returns that person's rows over the API exactly as it does in the app's own UI, and `allow read, create when IsAuthenticated` admits them. Three consequences, each of which is a mistake if you assume the opposite: - **You do not need `IsAnonymous` to make an entity reachable over an authenticated API.** The caller is somebody. An `allow … when IsAnonymous` rule is in fact the one thing an API-key caller can *never* satisfy. - **A missing credential is a `401`, not an anonymous request.** `ApiAuth { ApiKey = true }` never falls through to anonymous access; the request stops at the door. - **Only an API with no `Auth` runs anonymously**, and there `user` is null — so a row filter correlating to `user` matches nothing and denies, which is the correct answer for a caller who is nobody. ⚑ **You can check every row of that table against your own app rather than take it from here.** [Calling your own REST API from a test](https://osysharp.com/reference/testing/api-calls/) sends a real request to your published route from inside a `[Test]`, with or without a credential, and hands you the status back — so "an API key caller is authenticated" is a claim you can make the app answer: ```osy syntax Assert.Equal(401, Api.Get("/api/rest/v1/catalog/entities/Product").StatusCode); // nobody Assert.Equal(200, Api.Get("/api/rest/v1/catalog/entities/Product", apiKey: key).StatusCode); // somebody ``` ### Where the key lives {#api-key-storage} The platform stores each user's key as a **hash on that user's own principal row**, in two columns your `[Principal]` entity must declare by these exact names: ```osy syntax [Principal] entity User { [Unique, MaxLength(200)] string Email; [MaxLength(255)] string? ApiKeyHash; // the key in force [MaxLength(255)] string? ApiKeyHash2; // a second, so a key can be rotated without a gap security { allow read when IsAuthenticated; // ⛔ BOTH SLOTS. A stored key hash with no field-level `deny read` rides `Session.CurrentUser` to the // browser — the platform ships the whole [Principal] minus its MASKED properties. deny read ApiKeyHash when !IsAuthenticator; deny read ApiKeyHash2 when !IsAuthenticator; } } ``` `IsAuthenticator` is a policy **you declare** over your own grant table — it is not built in. See [auth bootstrap (login, before anyone is signed in)](https://osysharp.com/reference/security/auth-bootstrap/) for the three lines that declare it, and [acting for another principal](https://osysharp.com/reference/security/acting-for-another-principal/) for the whole shape worked through on an app whose API caller is a machine. Declaring `Auth = new ApiAuth { ApiKey = true }` on an app whose principal lacks them is a **compile error** naming both columns — without them no key can be minted and none can be verified, so the published route would be a `401` forever. You never write a key into source. The platform mints one for a named user and prints the plaintext `pk_…` **once**; only its hash is stored, and the caller then presents it in the `X-API-Key` header: ```bash osyrin app user apikey generate alice@example.com # prints the pk_… once osyrin app user apikey revoke alice@example.com # --secondary to drop only the rotation key ``` Because there are two columns, rotation has no gap: generate a second key while the first still works, move the callers over, then revoke the old one. ⚑ **In a test, ask for one by naming the principal** — [[testing-api-calls#credentials|`Api.KeyFor(P)`]]. "You never write a key into source" is about your APP's source and stays true; a `[Test]` mints a real one against its own throwaway branch, so the gated route above can actually be exercised rather than only refused. ⚠ **`app.Secrets` is a different thing and is not involved.** `app.Secrets` declares secrets your app *consumes* — an LLM key, an OAuth client secret. `ApiAuth` has no member that names a `Secret`, so there is nothing to declare there for an API key, and declaring one does not gate anything. ## Examples {#examples} A complete app that publishes one entity as read/create CRUD and one function as a POST route: ```osy title="basic" test app=api-rest-example entity Order { [Required, MaxLength(200)] string CustomerEmail; decimal Total; } decimal SubmitOrder(decimal total, decimal taxRate) { return total + total * taxRate; } app.Apis = [ new RestApi("Orders") { Route = "orders", Expose = [ new Crud() { Operations = [CrudOp.Read, CrudOp.Create] } ], Endpoints = [ new Endpoint(SubmitOrder) { Method = HttpMethod.Post, Path = "/submit", SuccessStatus = 201 }, ], }, ]; ``` Require an API key on every route. The key belongs to a USER, so the principal declares the two columns that hold it — and the entity's `security {}` then governs the API caller exactly as it governs that same person signed in: ```osy title="with-api-key" test app=api-rest-authed [Role] enum AppRole { Authenticator, Member } entity RoleGrant { [Required("Name the user this grant belongs to.")] User Grantee; [Required("Choose the role this grant confers.")] AppRole Level; security { allow read when IsAuthenticated; } } policy IsAuthenticator => RoleGrant.Any(g => g.Grantee == user && g.Level == AppRole.Authenticator); [Principal] entity User { [Unique, MaxLength(200)] string Email; [MaxLength(255)] string? ApiKeyHash; [MaxLength(255)] string? ApiKeyHash2; security { allow read when IsAuthenticated; // ⛔ BOTH SLOTS, or the stored key hash rides `Session.CurrentUser` to the browser. deny read ApiKeyHash when !IsAuthenticator; deny read ApiKeyHash2 when !IsAuthenticator; } } entity Product { [Required, MaxLength(200)] string Name; decimal Price; security { allow read when IsAuthenticated; // the API-key caller IS authenticated — no anonymous grant needed } } app.Apis = [ new RestApi("Catalog") { Route = "catalog", Auth = new ApiAuth { ApiKey = true }, Expose = [ new Crud() { Operations = [CrudOp.Read] } ], }, ]; ``` ## See also {#see-also} - [principal predicates (IsAuthenticated / IsAnonymous) and open reads](https://osysharp.com/reference/security/principal-predicates/) — `IsAuthenticated` / `IsAnonymous`, the predicates the table above resolves - [[AuthMethod] — a function an unauthenticated visitor may call](https://osysharp.com/reference/security/auth-method/) — signing a user in, for bearer-authenticated routes - [function](https://osysharp.com/reference/function/declaration/) — the functions an `Endpoint` publishes - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — `app.Secrets`, for the secrets your app CONSUMES; an API key is not one of them - [Calling your own REST API from a test](https://osysharp.com/reference/testing/api-calls/) — `Api.*`: calling these routes from your own `.test.osy`, and asserting the status each refusal answers --- # Class inheritance > A class can derive from another class with `class Circle : Shape`, inheriting its fields and its methods to any depth. A value of the derived type goes wherever the base is expected, and a `virtual` method can be replaced by an `override` one. `sealed` closes a class to further derivation. A class may derive only from a class — never from an entity, and never the reverse. ## Summary {#summary} A class derives from another with `:`, exactly as in C#. It inherits the base's fields and methods: ```osy title="a derived class inherits fields and methods" test app=class-inheritance class Shape { public string Name; public string Describe() { return Name; } } class Circle : Shape { public decimal Radius; } string DescribeACircle() { var c = new Circle { Name = "small", Radius = 2m }; return c.Describe(); // the method Shape declares, called on a Circle } ``` ## Signature {#signature} ```osy syntax class Derived : Base { … } // inherits Base's fields and methods sealed class Leaf { … } // no type may derive from Leaf ``` ## Description {#description} ### What does a subclass inherit? {#what-is-inherited} Fields and methods, to any depth. A three-level chain works the way it reads, and a member declared anywhere above is available below: ```osy title="inheritance is transitive" test app=class-inheritance-depth class Shape { public string Name; } class Round : Shape { public decimal Radius; } class Dot : Round { } string NameOfADot() { var d = new Dot { Name = "tiny", Radius = 0m }; return d.Name; // declared two levels up } ``` ### A derived value fits a base slot {#upcast} This is the point of a hierarchy: code written against `Shape` accepts every shape. The conversion is implicit and needs nothing written: ```osy title="a Circle goes wherever a Shape is expected" test app=class-inheritance-upcast class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string NameThrough() { Shape s = new Circle { Name = "c", Radius = 2m }; return s.Name; } ``` It is **one-way**, as in C#. A `Shape` is not assignable to a `Circle`, because not every shape is one — going the other way needs a [type test](https://osysharp.com/reference/class/type-tests/). The same rule applies wherever two values meet and one type has to describe both — a conditional, a `switch` expression, a `??` fallback. The answer is the **base** of the two: ```osy title="picking between a base and a derived value" test app=class-inheritance-upcast-positions class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string Pick(bool round, int kind) { var c = new Circle { Name = "circle", Radius = 2m }; var p = new Shape { Name = "plain" }; Shape a = round ? c : p; // the branches unify to Shape Shape b = kind switch { 1 => c, _ => p }; // so do the arms Shape d = a ?? c; // and so do the sides of `??` return a.Name + b.Name + d.Name; } ``` Because the result is a `Shape`, only `Shape`'s members are readable through it — reach for a [type test](https://osysharp.com/reference/class/type-tests/) to get back to `Radius`. **Two SIBLINGS take the type they are written into.** A `Circle` and a `Square` are both `Shape`s, but neither is the other, so there is no type to *infer* — and where the type is *written*, that is the answer: ```osy title="the target types the conditional" test app=class-inheritance-target-typed class Shape { public string Name; } class Circle : Shape { public decimal Radius; } class Square : Shape { public decimal Side; } class Plot { public Shape Primary; } string Show(Shape s) { return s.Name; } string Pick(bool round) { var c = new Circle { Name = "circle", Radius = 1m }; var q = new Square { Name = "square", Side = 2m }; Shape s = round ? c : q; // a declared local var p = new Plot { Primary = round ? c : q }; // a member return Show(round ? c : q) + s.Name + p.Primary.Name; // an argument } ``` It works wherever the target is written: a declared local, a parameter, a member, an assignment, a `return`, and the arms of a `switch` expression. What it does **not** do is invent one — `var s = round ? c : q;` writes the value into nothing, so there is nothing to take, and the compiler says so and names the fix. (Same in C#.) ### Can a `Circle[]` be used as a `Shape[]`? {#covariance} A `Circle[]` **is** a `Shape[]`, and needs nothing written — as in C#. This holds in every position: a local, a parameter, a return, a class member. ```osy title="Circle[] flows into Shape[]" test app=class-inheritance-array-covariance class Shape { public string Name; } class Circle : Shape { public decimal Radius; } int CountShapes(Shape[] shapes) { return shapes.Count(); } int HowMany() { Circle[] cs = [new Circle { Name = "a", Radius = 1m }, new Circle { Name = "b", Radius = 2m }]; Shape[] xs = cs; return CountShapes(xs); } ``` A **`List` is different, and deliberately so**: it can be appended to, so a `List` is *not* a `List`. Handing one over would let the receiver add a plain `Shape` to your list of circles. If the receiver only reads, declare it `Shape[]` — a `List` passes straight into a read-only sequence. **An array of a type that HAS subtypes cannot be written through.** This is the other half of the rule above, and the reason the conversion is safe: since a `Shape[]` may really be a `Circle[]`, storing a plain `Shape` into one would leave an element missing the members the narrower array promises. ```osy title="✗ writing into an array that may be a Circle[]" syntax Shape[] xs = circles; // fine — read it all you like xs[0] = new Shape { Name = "x" }; // refused: `Shape` has subtypes, so this array may be a `Circle[]` ``` C# allows that write and throws `ArrayStoreException` when it runs; here it is the same rule, moved to where you can see it. An array of a type nothing derives from — including every scalar array, `int[]`, `double[]`, `string[]` — is written exactly as in C#. When you need to write into a polymorphic sequence, use a `List`: it is invariant, which is what makes it safe to write. ### `sealed` closes the class {#sealed} `sealed` says no type may derive. Write it when a class is meant to be the end of its line: ```osy syntax sealed class Candle : Mark { } // deriving from Candle is a compile error ``` ### Specialising a method: `virtual` and `override` {#override} A base method marked `virtual` may be replaced by a derived one marked `override`. The call runs the method of the value's **actual** type, whatever type the slot holding it is declared as: ```osy title="the derived body runs through a base-typed slot" test app=class-inheritance-override class Shape { public string Name; public virtual decimal Area() { return 0m; } } class Circle : Shape { public decimal Radius; public override decimal Area() { return Radius * Radius * 3m; } } decimal AreaThroughTheBase() { Shape s = new Circle { Name = "c", Radius = 2m }; return s.Area(); // 12 — Circle's body, not Shape's } ``` **Both words are required, each for a different mistake.** Without `virtual` on the base, adding a method to a base class would silently change what every subclass sharing that name does. Without `override` on the derived one, an accidental name collision would read as a deliberate specialisation. Redeclaring a method that is not `virtual` is refused, and the refusal names the word that is missing. **`base.M()` calls the version the derived class inherits** — what makes an override able to EXTEND the base rather than replace it: ```osy title="an override that builds on its base" test app=class-inheritance-base-call class Shape { public string Name; public virtual decimal Area() { return 2m; } } class Circle : Shape { public decimal Radius; public override decimal Area() { return base.Area() + 1m; } // 3 — Shape's answer, plus one } decimal AreaOfACircle() { Shape s = new Circle { Name = "c", Radius = 1m }; return s.Area(); } ``` `base` looks up the chain, not just one step: if the immediate parent declares nothing by that name, the call runs the nearest ancestor that does. It is only meaningful inside a class member's body, and a local variable named `base` shadows it. ### Constructing the base: `: base(…)` {#base-constructor} A derived class's constructor runs the base class's constructor first, and says which one with `: base(…)`: ```osy title="the base constructor runs first" test app=class-inheritance-base-ctor class Shape { public string Name; public decimal Width; public Shape(string n, decimal w) { Name = n; Width = w; } } class Circle : Shape { public decimal Radius; public Circle(string n, decimal r) : base(n, r * 2m) { Radius = r; } } string BuildOne() { var c = new Circle("small", 2m); return c.Name; // "small" — set by Shape's constructor } ``` The arguments are an ordinary argument list: as many as the base constructor takes, in any expression, and by name (`: base(n, w: 4m)`) if you prefer. `: base()` is how you call a parameterless base constructor explicitly. A constructor with **no** initializer runs the base's *parameterless* constructor, exactly as in C#. So if the base declares a constructor that takes arguments, the derived one has to say what to pass — and the compiler asks for it by name. A base class with no constructor at all needs nothing: its fields take the defaults their declarations give. Members the base constructor assigns count as assigned, so you do not have to supply them again at the create site. `: this(…)` — chaining to another constructor of the same class — needs constructor overloading, which is not available yet. ### `abstract` — a shape to derive from {#abstract} An `abstract class` cannot be created; it exists for other types to fill in. An `abstract` method declares **what** a subclass must provide and has no body: ```osy title="the obligation, and the class that meets it" test app=class-inheritance-abstract abstract class Shape { public string Name; public abstract decimal Area(); // no body — every Shape has one, but Shape does not say what } class Circle : Shape { public decimal Radius; public override decimal Area() { return Radius * Radius * 3m; } } decimal AreaOfACircle() { Shape s = new Circle { Name = "c", Radius = 2m }; return s.Area(); // 12 — Circle's body } ``` An abstract method is already the thing a subclass overrides, so it needs no `virtual`. The first **concrete** class below it must provide a body — a class that does not is asked for one by name, unless it is `abstract` too, in which case the obligation passes down. `abstract` and `sealed` are opposites and cannot both be written: one says the type must be derived from, the other that it must not. ### `protected` — visible down the chain, and nowhere else {#protected} A class member is `private` unless it says otherwise, and `private` means *this class only* — a subclass cannot see it. `protected` is the middle setting: reachable from the declaring class and from anything that derives from it. ```osy title="a subclass reads it; nothing else can" test app=class-inheritance-protected class Shape { protected string Tag; // subclasses may read and write it private string secret; // this class only, even for a subclass public Shape(string t) { Tag = t; secret = "hidden"; } protected string Describe() { return "[" + Tag + "]"; } // methods take it too } class Circle : Shape { public decimal Radius; public Circle(string t, decimal r) : base(t) { Radius = r; } public string Label() { return Tag + Describe(); } // both reachable here } string BuildLabel() { var c = new Circle("c", 2m); return c.Label(); // "c[c]" } ``` It reaches the whole chain, not one step: a class deriving from `Circle` sees `Shape`'s protected members too. From outside the hierarchy the member does not exist — `c.Tag` in a top-level function is a compile error naming the fix, which is to derive from the class rather than to reach into it. ### Can a class derive from an entity? {#kinds} A class may derive only from a class. Mixing the kinds is refused in both directions, because they are different things wearing one word: an [entity hierarchy](https://osysharp.com/reference/entity/inheritance/) is rows in a table with a discriminator column, and a class is a value in memory with no table at all. ## Errors {#errors} | you wrote | what you get | |---|---| | a method already declared on the base | refused, naming `virtual`/`override` as what is missing | | `class C : SomeSealedClass` | refused — `sealed` means no type may derive | | `class C : SomeEntity` (or an entity deriving from a class) | refused — a class and an entity are different kinds | | `Circle c = someShape;` | refused — the upcast is one-way; test the type instead | | `var s = f ? circle : square;` | refused — two siblings have no common type and `var` supplies no target; declare the type, or cast one branch | | a `List` where a `List` is wanted | refused — a `List` can be appended to, so it is invariant; declare `Shape[]` if it is only read | | `shapes[0] = new Shape { … }` where `Shape` has subtypes | refused — the array may be a `Circle[]`; read it freely, or use a `List` to write | ## See also {#see-also} - [Interfaces — a contract several types can satisfy](https://osysharp.com/reference/class/interfaces/) — a contract with no bodies and no state, which a type may satisfy SEVERAL of (a base class it may have only one of) - [Testing which class a value is](https://osysharp.com/reference/class/type-tests/) — asking which type a value actually is, and narrowing to it - [class methods](https://osysharp.com/reference/class/methods/) — behaviour with a receiver - [entity Sub : Base](https://osysharp.com/reference/entity/inheritance/) — the same word for rows, and why it works differently - [Classes](https://osysharp.com/reference/class/index/) — what a class is --- # Classes > A class is an in-memory shape — data plus the behaviour that belongs to it — and it never touches the database. That is the whole distinction from an entity: an entity is a table, a class is something you build, pass, and compute with in a function or a component. Classes have a constructor and methods, exactly as in C#, and like a C# class they are REFERENCE types: `var b = a;` aliases rather than copies, and `list[i].Field = x` sticks. ## Summary {#summary} A `class` is an **in-memory shape**: fields and the behaviour that belongs to them. It is not persisted and has no table — that is the one line that separates it from an [entity](https://osysharp.com/reference/entity/declaration/). Like a C# class it is a **reference type** ([[class-index#reference|what that means for assignment]]). Reach for a class when you need a structured value to compute with inside a function or a component: a parsed request, a calculation's intermediate, a projection's target, a small bundle of related fields you pass around. If you're deciding between the two: **does it need to be stored and queried?** Yes → an entity. No → a class. ## Description {#description} ### A value, not a row {#vs-entity} An entity lives in the database; the platform loads it, tracks your edits, and commits them. A class does none of that — you `new` it, read and write its fields, hand it to another function, and it vanishes when the work is done. No schema, no migration, no security rules: it is just a value in memory, like any C# object. It carries its own [constructor](https://osysharp.com/reference/class/constructors/) and [methods](https://osysharp.com/reference/class/methods/): ```osy title="a value with a constructor and a method" test app=class-index class Money { public decimal Amount; public string Currency; // the ctor assigns the required Currency, so `new Money(9.5m, "USD")` needs no initializer — the compiler infers it public Money(decimal amount, string currency) { Amount = amount; Currency = currency; } public string Label() => Amount.ToString("F2") + " " + Currency; } ``` Build one and read its label — the constructor runs, then the method runs on the value: ```osy title="build one and read its label" run app=class-index [Test] void Builds_And_Labels() { var m = new Money(9.5m, "USD"); Assert.Equal("9.50 USD", m.Label()); } ``` ### Does `var b = a;` copy it, or point at it? {#reference} It points at it. **A class is a REFERENCE type, exactly like a C# `class`** — "value" above describes what a class is *for* (a shape you compute with, with no table behind it), never how assignment behaves. Three consequences, and all three are the C# ones: - `var b = a;` makes `b` **another name for the same object**. A write through `b` is visible through `a`. - `list[i].Field = x` **sticks** — the indexer hands back the object, not a copy of it, so you can edit rows in place. - A list you filtered holds **the same objects** as the list you filtered it from, so editing through one is visible through the other. ⚑ **In a component, that in-place write also RE-RENDERS** — a render slot reading a class field is tracked like any other read, so you never need to reassign the list to make the screen move. What you cannot do is point a control's two-way `value:` at a class field. Both halves, with compiled proof: [[ui-reactivity#class-values]]. ```osy title="assignment aliases, and an edit through an index sticks" test app=class-index class Ticket { public string Code; public decimal Price; public Ticket(string code, decimal price) { Code = code; Price = price; } } ``` ```osy title="the three things people write around when they assume a copy" run app=class-index [Test] void A_Class_Is_A_Reference() { var a = new Ticket("T1", 10m); var b = a; b.Price = 99m; Assert.Equal(99m, a.Price); // same object — `b` was never a copy var rows = new List(); rows.Add(new Ticket("T2", 1m)); rows.Add(new Ticket("T3", 2m)); rows[0].Price = 42m; Assert.Equal(42m, rows[0].Price); // an edit through the indexer sticks var dear = rows.Where(t => t.Price > 1m).ToList(); dear[0].Price = 50m; Assert.Equal(50m, rows[0].Price); // the filtered list holds the SAME objects var missing = rows.FirstOrDefault(t => t.Code == "nope"); Assert.True(missing == null); // no match is null, not an empty Ticket } ``` ⚑ [`with`](https://osysharp.com/reference/class/with/) is the one place a copy happens, and that is the point of it: `a with { Price = 5m }` builds a **new** object and leaves `a` alone. It is opt-in copying, not evidence that assignment copies. ### It has a constructor {#constructor} A class declares one [constructor](https://osysharp.com/reference/class/constructors/) — its name is the class name, it takes no return type, and it runs when you write `new T(args)`. The constructor body runs first; object-initializer syntax (`{ Member = value }`) applies after it. Use the constructor for the setup a valid instance always needs. ### It has methods {#methods} Behaviour that belongs to a shape lives on the shape. A [method](https://osysharp.com/reference/class/methods/) has a receiver and is called as `value.Method(...)` — the natural home for logic that is *about* this value rather than about the database. A method body resolves function-style with the class as its receiver, the same mechanism a component's `action` uses. ### It has properties {#properties} A [property](https://osysharp.com/reference/class/properties/) reads and writes like a field but runs a body on access — a value computed from other fields (`Total => Qty * Price`), a setter that validates a write, or an auto-property (`{ get; set; }`) whose storage the platform synthesizes. It is a field-shaped pair of methods, so it works everywhere a method does, the browser included. ### Its fields can have defaults {#defaults} A field can carry an initializer — `decimal Rate = 0.25m;`. It runs at construction, before the constructor body and before any object initializer, exactly as in C#: the constructor (and every read) sees the declared value unless something later overwrites it. ```osy title="a field with a default" test app=class-index class Cart { public decimal Rate = 0.25m; } ``` ```osy title="the default is there before you touch it" run app=class-index [Test] void Field_Default_Applies() { var c = new Cart(); Assert.Equal(0.25m, c.Rate); // the declared default, applied at construction var d = new Cart { Rate = 0.1m }; Assert.Equal(0.1m, d.Rate); // an object initializer overrides it } ``` ### Visibility follows C# {#visibility} A top-level `class` is `internal` by default (an entity or enum is `public`) — see [type visibility (public / internal)](https://osysharp.com/reference/types/visibility/). Mark it `public` when code in another namespace needs to name it. ## See also {#see-also} - [constructor](https://osysharp.com/reference/class/constructors/) — the single constructor and how it composes with object initializers - [Class inheritance](https://osysharp.com/reference/class/inheritance/) — deriving one class from another, and `sealed` - [Interfaces — a contract several types can satisfy](https://osysharp.com/reference/class/interfaces/) — a contract several types satisfy, and calling through it - [Testing which class a value is](https://osysharp.com/reference/class/type-tests/) — asking which type a value actually is - [class methods](https://osysharp.com/reference/class/methods/) — behaviour with a receiver, called `value.Method(…)` - [class properties](https://osysharp.com/reference/class/properties/) — members that read/write like a field but run a body on access - [`readonly` fields](https://osysharp.com/reference/class/readonly/) — a field only the constructor may set - [Copying a class with changes](https://osysharp.com/reference/class/with/) — copying a value and replacing some of its fields - [Method overloads](https://osysharp.com/reference/class/overloads/) — several methods sharing a name, told apart by their parameters - [`static` methods](https://osysharp.com/reference/class/static/) — a method that belongs to the type rather than to an instance - [`params` parameters](https://osysharp.com/reference/class/params/) — a method callable with any number of trailing arguments - [entity](https://osysharp.com/reference/entity/declaration/) — the persisted counterpart, when the shape needs a table - [type visibility (public / internal)](https://osysharp.com/reference/types/visibility/) — why a class defaults to `internal` --- # Comparing classes > `==` on two class values compares them BY VALUE, field by field, rather than by reference. A class is a value you build rather than a row you hold, and the runtime rebuilds it freely — so two separately constructed values with the same contents are equal, and a class rebuilt on the next render still equals the one you kept. ## Summary {#summary} Two class values are equal when **their fields are equal**: ```osy title="value equality, not reference equality" test app=class-equality class Money { public decimal Amount; public string Currency; } bool SamePrice() { var a = new Money { Amount = 9.50m, Currency = "USD" }; var b = new Money { Amount = 9.50m, Currency = "USD" }; return a == b; // true — two values, one content } ``` `a` and `b` were built separately and are still equal. That is the rule, and it is the one place Osy# deliberately answers differently from C#'s `class`. ## Signature {#signature} ```osy syntax a == b // true when both are the SAME class and every field is equal a != b // the negation a == null // a class is a reference type, so this is a legitimate check ``` ## Description {#description} ### Why value equality {#why} A class is an **in-memory value**, not a row: it has no table and no id, and the platform rebuilds it wherever it needs to. A `new` written inside a component's `render` is rebuilt on every render. A class handed between the browser and the server is serialised and reconstructed on the far side. Nothing preserves object identity across any of that. So reference equality would not merely be a different answer — it would be an answer that can never be `true` for two values you did not personally hold onto within a single expression. That is why the rule is value equality: it is the only question the runtime can answer honestly, and it is the one authors are asking. If you are coming from C#: an Osy# `class` behaves like a C# **`record`**, not like a C# `class`. ### What "equal fields" means {#field-comparison} Field comparison is the ordinary `==` applied to each field, so the rule composes: | a field holding | compares by | |---|---| | a scalar (`int`, `string`, `decimal`, `DateTime`, an enum) | its value | | another class | its fields, recursively | | an entity | that entity's identity, exactly as `==` on an entity does | | a `Func<…>` / `Action<…>` | the lambda it came from — see below | | nothing (never assigned) | `null`, which is what an unset field is | Two values of **different** classes are never equal, however identical their fields. ### A field holding a function {#function-fields} A selector field compares by **which lambda it is**, not by the object wrapping it: ```osy title="a shape carrying a selector" test app=class-equality-func class Column { public string Label; public Func Value; } ``` Two `Column` values written from the same `r => r.Title` are equal; two written from different lambdas are not. This is the same question C# asks of a method group, and it is what lets a shape that carries behaviour — a table column, a formatting rule — be compared at all. Without it a single function field would make every such value unequal to every other, including to itself one render later. ### Entities compare differently, and should {#entities} An [entity](https://osysharp.com/reference/entity/declaration/) is a row, so two entity values are equal when they are **the same row** — its identity, not its current field values. Two rows with identical columns are still two rows. A class has no identity to compare, which is exactly why its contents are the answer. [Comparing entity rows](https://osysharp.com/reference/entity/equality/) has that rule in full, and what it means for `Contains`/`IndexOf`/`Remove` over a list of rows. ## Examples {#examples} ```osy title="a rebuilt value still matches the one you kept" test app=class-equality-render class Column { public string Name; public Func Value; } [Composable] component SortHeader(Column[] columns) { Column sortBy = columns[0]; bool descending = false; // `columns` is rebuilt every render, so `c` is not the same OBJECT as `sortBy` — it is the same VALUE. // Clicking the sorted column toggles direction; clicking another one selects it. action Choose(Column c) { if (sortBy == c) { descending = !descending; } else { sortBy = c; descending = false; } } render { Row { foreach (var c in columns) { Pressable(onClick: () => Choose(c)) { Text(c.Name); } } } } } ``` ## Errors {#errors} | Message | Cause | Fix | |---|---|---| | `cannot compare 'X' with 'Y'` | The two operands are unrelated types. | Compare values of the same class, or compare a field of each. | ## See also {#see-also} - [Classes](https://osysharp.com/reference/class/index/) — what a class is, and when to reach for one instead of an entity - [class properties](https://osysharp.com/reference/class/properties/) — declaring the fields this rule compares - [Copying a class with changes](https://osysharp.com/reference/class/with/) — copying a value with some fields replaced, which this rule is what makes coherent - [Generic classes](https://osysharp.com/reference/class/generics/) — the `Column` shape used above - [Comparing entity rows](https://osysharp.com/reference/entity/equality/) — the other half of this rule: why an entity compares by identity instead - [entity](https://osysharp.com/reference/entity/declaration/) — what a row is, and how you read one back --- # Copying a class with changes > `with` makes a COPY of a class value and replaces the fields you name. Everything you do not name comes from the value you copied, and the original is left untouched — so it is how you derive one value from another without rebuilding it field by field, and without mutating something another part of the program is still holding. ## Summary {#summary} `with` copies a class value and replaces the fields you name: ```osy title="a copy with one field changed" test app=class-with class Money { public decimal Amount; public string Currency = "USD"; public string Note = ""; } string Rename() { var fee = new Money { Amount = 25m, Currency = "SEK", Note = "late fee" }; var refund = fee with { Amount = 0m }; return refund.Currency; // "SEK" — carried over, not re-defaulted } ``` `refund` is a **new value**. It took its `Amount` from the initializer and everything else — `Currency`, `Note` — from `fee`, which is unchanged. ## Signature {#signature} ```osy syntax value with { Field = expr, … } // a copy of `value`, with those fields replaced value with { } // a plain copy a with { X = 1m } with { Y = 2m } // chains; each copy is made from the one before ``` `with` is available on any [class](https://osysharp.com/reference/class/index/). It is not available on an `entity`, or on a scalar — see [[#errors|Errors]]. ## Description {#description} ### The fields you do not name come from the value you copied {#copied-fields} This is the whole point, and it is the part worth testing when something looks wrong. A `with` does **not** start from the class's declared defaults and it does not re-run field initializers: ```osy title="declared defaults do not come back" test app=class-with-defaults class Settings { public string Theme = "light"; public decimal Zoom = 1m; } string Keep() { var dark = new Settings { Theme = "dark", Zoom = 2m }; var zoomed = dark with { Zoom = 3m }; return zoomed.Theme; // "dark" — the copy's value, NOT the declared "light" } ``` ### The original is never modified {#immutable} `with` produces a value; it does not write through to the one it copied. Anything else still holding the original sees exactly what it saw before: ```osy title="the donor is untouched" test app=class-with-donor class Money { public decimal Amount; public string Note = ""; } decimal Both() { var original = new Money { Amount = 10m, Note = "invoice" }; var adjusted = original with { Amount = 25m }; return original.Amount + adjusted.Amount; // 35 — 10 and 25, two values } ``` ### A copy keeps the type it actually is {#runtime-type} If you copy a value held in a base-typed variable, the copy is the type the **value** is, not the type the variable is declared as: ```osy title="a Dog held as an Animal copies to a Dog" test app=class-with-subtype class Animal { public string Name = "?"; } class Dog : Animal { public decimal Legs = 4m; } bool StillADog() { Animal held = new Dog { Name = "rex", Legs = 3m }; var renamed = held with { Name = "fido" }; return renamed is Dog; // true, and its Legs is still 3 } ``` ### Why there is no `record` keyword {#no-record} In C#, `with` works on a `record` and not on a plain `class`, because the two differ in how they compare. In Osy# they do not: a class already compares [by value](https://osysharp.com/reference/class/equality/), which is what a C# `record` is. A second keyword would therefore separate nothing, so `with` is simply available on every class. A consequence worth knowing: a plain copy **equals** the value it came from. ```osy title="a copy with nothing replaced is equal" test app=class-with-equality class Point { public decimal X; public decimal Y; } bool SameValue() { var p = new Point { X = 1m, Y = 2m }; return p == p with { }; // true — same class, same fields } ``` ### `readonly` fields still cannot be set {#readonly} A [`readonly`](https://osysharp.com/reference/class/readonly/) field is one only the constructor may assign, and a `with` is not a constructor — it copies an already-built value and then writes over it. To vary a `readonly` field, construct the value instead. ## Examples {#examples} ```osy title="deriving a series of values from one" test app=class-with-series class Quote { public string Customer; public decimal Net; public decimal Vat = 0m; public string Status = "draft"; } decimal Finalize() { var draft = new Quote { Customer = "Acme", Net = 100m }; var taxed = draft with { Vat = 25m }; var sent = taxed with { Status = "sent" }; // Customer and Net rode through both copies; nobody had to restate them. return sent.Net + sent.Vat; // 125 } ``` ## Errors {#errors} | Message | Cause | Fix | |---|---|---| | ``with` copies an object, and a `decimal` is not one` | The value on the left is a scalar, which has no fields to replace. | Use ordinary arithmetic or assignment; `with` applies to a class. | | ``with` copies an in-memory `class`, and 'X' is an `entity`` | The value on the left is a stored row. Copying one would silently mean either a second row or a duplicate of this one. | Create the row you want (`new X { … }`), or change the fields on the row you have. | | `entity 'X' has no property 'Y'` | The initializer names a field the class does not declare. | Check the field name against the declaration. | | `'X.Y' is readonly` | A `readonly` field cannot be set by a copy. | Pass the value to the constructor instead. | ## See also {#see-also} - [Classes](https://osysharp.com/reference/class/index/) — what a class is, and when to reach for one instead of an entity - [Comparing classes](https://osysharp.com/reference/class/equality/) — why a class compares by value, which is why `with` needs no `record` keyword - [`readonly` fields](https://osysharp.com/reference/class/readonly/) — the one kind of field a copy may not replace - [constructor](https://osysharp.com/reference/class/constructors/) — building a value from scratch rather than from another one - [entity](https://osysharp.com/reference/entity/declaration/) — why a stored row is copied differently --- # Generic classes > A class can declare type parameters, so one shape serves every type it is used with instead of being copied per entity. The type argument is written where the class is used (`Column`), and every member read off it substitutes — which is what binds a selector's parameter to the real row type and makes its body checkable. A METHOD can declare its own type parameters too, and those are bound by the call rather than by the receiver. ## Summary {#summary} A class that describes **how to work with a value** should not have to know **which** value. Declare it with a type parameter and one declaration serves every type: ```osy title="one column shape, any row type" test app=class-generics class Column { public string Label; public Func Value; } ``` Without generics that shape has to be copied once per entity — a `ReportColumn`, a `PersonColumn` — each identical except for one type. With them, `Column` and `Column` are two **types** from one **declaration**. ## Signature {#signature} ```osy title="declaring the parameter, supplying the argument" syntax class Name { … } // one type parameter class Name { … } // several, comma-separated Name // a CONSTRUCTED type: the argument supplied at the use site new Name { … } // …and at construction ``` A type parameter is in scope over the whole class body — including in its methods' signatures. A **method** may also declare parameters of its own, which the call binds rather than the receiver: ```osy title="a method's own parameter, bound by the call" syntax class Util { public T Echo(T v) { … } } // the method's own parameter T Echo(T v) { … } // a top-level function, the same way ``` `entity` cannot be generic. ## Description {#description} ### The type argument goes where the class is USED {#use-site} The declaration names the parameter; the use site supplies the argument. Between them, the compiler knows what `T` is at every point: ```osy title="the argument is written at the use site" test app=class-generics entity Report { [MaxLength(80)] string Title; decimal Total; } [Composable] component Grid(T[] rows, Column[] columns) { render { foreach (var r in rows) { Row { foreach (var c in columns) { Text(c.Value(r)); } } } } } [Page("/")] [AllowAnonymous] component Home() { var reports = Report.ToList(); // the read is a MEMBER — a render body holds values, it does not fetch render { Grid(rows: reports, columns: [ new Column { Label = "Title", Value = r => r.Title }, new Column { Label = "Band", Value = r => r.Total > 1000 ? "large" : "small" } ]); } } ``` `Grid` mentions no entity at all. `Column` mentions no entity. The only place `Report` appears is the call site — which is exactly the point. ### Reading a member substitutes the argument {#substitution} `Value` is declared `Func`. Read off a `Column` it **is** a `Func`, so the lambda's parameter binds to a real row and its body is checked against it: ```osy title="the selector's parameter is the row type — and typos are caught" syntax new Column { Value = r => r.Title } // ✓ r is a Report new Column { Value = r => r.Nmae } // ✗ 'Report' has no property 'Nmae' ``` That substitution is the whole feature. Passing the wrong one is caught too — a `Column` where a `Column` is expected is a different type, not merely a differently-labelled `Column`. ### Where a type parameter may appear {#positions} `T` is first-class **on its own**, as an **array**, and inside a **function type**: ```osy title="the shapes a member may take" test app=class-generics class Holder { public T Row; // the type parameter itself public T[] Rows; // an array of it public Func Read; // a selector over it } ``` What is not built yet is `T` inside a **mutable collection or another generic type** — `List`, `HashSet`, `Dictionary`. Those carry a collection kind and a value slot that the compiler derives from the declaration alone, so they need their own storage rather than being let through. The refusal names the three spellings that do work. An unset member typed `T` reads `default(T)`, decided by the type argument: a `Holder` reads `0m`, a `Holder` reads null — because null *is* `default` for a type with no meaningful zero. ### Methods can have their OWN type parameters {#method-generics} A method may declare type parameters that the class does not, and they are bound by the **call** rather than by the receiver — inferred from the argument types: ```osy title="one method, a different type at every call" test app=class-generic-methods class Util { public T Echo(T v) { return v; } public string Describe(T v) { return "described"; } } string UseIt() { var u = new Util(); var n = u.Echo(2m); // T is decimal here var s = u.Echo("hello"); // …and string here, from the same declaration return s; } ``` This is the difference worth holding on to: a generic **class** fixes its argument once, where it is used (`Column`), and every member read off it substitutes that one answer. A generic **method** decides per call. Write the arguments explicitly when inference has nothing to read them from — a type parameter that appears in no parameter cannot be inferred, and the compiler says so rather than guessing: ```osy title="explicit type arguments" test app=class-generic-methods string Explicitly() { var u = new Util(); return u.Echo("hello"); } ``` A **top-level function** may be generic the same way, and so may a method on a class that is itself generic — there the two sets are bound by different things, the class's by the receiver and the method's by the call. A method may **not** reuse one of its class's parameter names: the two would be different types wearing one name, and nothing in the source would show the reader which is which. ### Classes only {#no-generic-entity} An `entity` cannot be generic. An entity is a table, and a table has no columns until `T` is known: ```osy title="a table cannot be generic" syntax entity Row { string Label; } // ✗ — write `class Row` for an in-memory shape ``` ## Examples {#examples} A comparator and a formatter are the same shape as a column, which is why this generalises past grids: ```osy title="the same idea, two other uses" test app=class-generics-more class Sorter { public string Label; public Func Key; } class Formatter { public Func Render; } ``` Several type parameters are written the way C# writes them: ```osy title="more than one parameter" test app=class-generics-more class Mapping { public Func Read; public Func Write; } ``` ### Deriving from a generic {#deriving} A base or a contract may be **constructed** — `: Box`, `: IRepo`. The members that arrive are substituted, so the subtype holds the closed type and not the parameter: ```osy title="closing a generic base" test app=class-generics-derive class Box { public T Value; public T Get() { return Value; } } // `Value` is an `int` on IntBox, so ordinary arithmetic works on it. class IntBox : Box { public int Doubled() { return Value * 2; } } ``` The subtype may stay generic and pass its own parameter on, and a third type close it. Substitution **composes** through the chain, so `Leaf.Value` is a `string`: ```osy title="passing a parameter on" test app=class-generics-derive class Mid : Box { public string Tag = "mid"; } class Leaf : Mid { } ``` A contract works the same way, and an implementor satisfies it **at the arguments it named** — a `TextRepo` is an `IRepo` and is not an `IRepo`: ```osy title="a generic contract" test app=class-generics-derive interface IRepo { T Fetch(); void Store(T v); } class TextRepo : IRepo { public string Held = ""; public string Fetch() { return Held; } public void Store(string v) { Held = v; } } ``` A `where` on a subtype goes after the base list, exactly as in C#: ```osy title="passing a constraint on" test app=class-generics-derive class Shape { public string Kind = "shape"; } class Holder where T : Shape { public T Held; } class ShapeHolder : Holder where T : Shape { } ``` ## Errors {#errors} | What you wrote | What you get | |---|---| | `entity Row { … }` | *'Row' is an `entity`, and an entity cannot be generic — it is a table, and a table has no columns until its type argument is known.* | | `public List Rows;` on a `class Holder` | *'Holder.Rows' is typed `List`, and a type parameter is not supported inside a mutable collection or a generic type yet — it works on its own (`T Rows;`), as an ARRAY (`T[] Rows;`), or inside a function type (`Func Rows;`).* | | `Column` | *'Column' takes 1 type argument (T), but 2 were written.* | | `u.Echo(2m)` on `T Echo(T v)` | *'Echo' declares 1 type parameter ('T'), but 2 were given.* | | calling `string Make()`, which mentions `T` in no parameter | *'Make' cannot infer its type parameter 'T' from these arguments … Write the type argument explicitly: `Make(…)`.* | | `public string Show(T v)` inside a `class Box` | *'Show' declares a type parameter 'T', and so does the type that declares it … Rename one of them.* | | `c.Add(1m)` where `Add` declares no type parameters | *'Add' declares no type parameters, so the type argument in `Add<…>(…)` binds to nothing … Drop the type arguments.* | | `Column` with no argument | *'Column' is generic — it needs a type argument for 'T'.* | | a `Column` where a `Column` is expected | *expects `Column[]` for 'columns', but got `Column[]`.* | | `class Bad : Box` on a `class Box` | *'Box' takes 1 type argument (T), but 2 were written on `Bad`.* | | `class Bad2 : NotGeneric` | *'NotGeneric' is not generic, so `Bad2 : NotGeneric` has nowhere to put those arguments.* | | `class BadBox : Box` on a `class Box where T : Shape` | *'Box' constrains 'T' to 'Shape', and 'int' is not a class at all — a bound names a type to derive from.* | | `IRepo r = new IntRepo();` where `IntRepo : IRepo` | *cannot implicitly convert 'IntRepo' to 'IRepo'.* | ## See also {#see-also} - [Func](https://osysharp.com/reference/ui/function-value/) — `Func` as a value: what a selector IS, and why its body reads only its parameters - [Classes](https://osysharp.com/reference/class/index/) — the class itself: a value shape, never a table - [class properties](https://osysharp.com/reference/class/properties/) — members that run a body on access - [component](https://osysharp.com/reference/ui/component/) — generic components, which take their type argument by inference from the call site --- # Interfaces — a contract several types can satisfy > An `interface` declares what a type must do without saying how — methods and property contracts, no bodies and no state. A class may implement several of them alongside its base class, a value typed as the interface accepts any implementor, and the call runs the implementation the value actually holds. ## Summary {#summary} An **`interface`** is a contract: what a type must provide, with no bodies and no state. ```osy title="a contract and two implementations" test app=class-interfaces interface IBlobStore { string Put(string key, string body); string Name { get; } } class S3Store : IBlobStore { public string Put(string key, string body) { return "s3://" + key; } public string Name { get; } = "s3"; } class GcsStore : IBlobStore { public string Put(string key, string body) { return "gs://" + key; } public string Name { get; } = "gcs"; } ``` A value typed as the interface accepts either, and the call runs whichever it holds: ```osy title="the call follows the value, not the slot" test app=class-interfaces string Upload(IBlobStore store, string key) { return store.Put(key, "…"); // "s3://k" or "gs://k" — decided by what `store` IS } ``` ## Signature {#signature} ```osy syntax interface IName { ReturnType Method(params); // an obligation to DO something Type Property { get; } // an obligation to ANSWER something Type Property { get; set; } // …and to accept one } class Name : Base, IOne, ITwo { … } // one base class, then any number of contracts interface IBoth : IOne, ITwo { } // an interface may extend others ``` Members are **public** without saying so, and **abstract** without saying so — that is what an interface is. ## Description {#description} ### Interface or abstract class? {#which} Both let you call through a shape rather than a concrete type. Choose by what you need to share: | | `interface` | `abstract class` | |---|---|---| | shared **behaviour** (a body) | no | yes | | shared **state** (a field) | no | yes | | how many a type may have | **many** | one | An interface is the right default for "these types all do X" — a store, a formatter, a notifier. Reach for an [abstract class](https://osysharp.com/reference/class/inheritance/) when implementors should share code, not just a shape. ### Implementing one {#implementing} A type lists its contracts after its base, and must provide **every** member — the compiler names the ones it is missing. An inherited implementation counts: ```osy title="the base already answers the contract" test app=class-interfaces class Logged : S3Store { } // Put/Name come from S3Store, so `Logged` is an IBlobStore too ``` An `abstract class` may implement a contract **partially** and leave the rest to its subclasses. ### Holding and testing one {#using} An interface is an ordinary type: a field, a parameter, a return, a collection element. `is` narrows back out of it: ```osy title="a list of contracts, and narrowing out" test app=class-interfaces string Describe(List stores) { var s = ""; foreach (var store in stores) { s = s + store.Name; if (store is GcsStore) { s = s + "(google)"; } } return s; } ``` ### What an interface may not do {#refusals} Each of these is refused with the reason, not a parse error: - **It cannot be created.** `new IBlobStore()` has no body to run — create one of the implementors. - **It holds no state.** A field is refused; a property contract (`int Count { get; }`) is how you require a value. - **Its members take no body.** Behaviour shared between implementors belongs on an abstract class. - **An `entity` implements none.** A row lives in one table told apart by one discriminator; a contract is a compile-time promise with nothing to store. Move the behaviour to a `class`. ⚠ **A generic contract cannot be inherited yet** — `class R : IRepo` is refused, and so is `class B : Box`. That is the generic-inheritance limit, not an interface one; the compiler says so where you write it. ## Examples {#examples} Choosing an implementation at run time — the shape this exists for: ```osy title="pick a store, then use it through the contract" test app=class-interfaces string Store(bool useGcs, string key) { IBlobStore store = new S3Store(); if (useGcs) { store = new GcsStore(); } return store.Name + " " + store.Put(key, "payload"); } ``` Two contracts on one type: ```osy title="a type may promise several things" test app=class-interfaces interface IAudited { string Who(); } class AuditedS3 : S3Store, IAudited { public string Who() { return "auditor"; } } string Trace(IAudited a) { return a.Who(); } ``` ## See also {#see-also} - [Class inheritance](https://osysharp.com/reference/class/inheritance/) — `class B : A`, `virtual`/`override`/`abstract`, and when a base class is the better shape - [class methods](https://osysharp.com/reference/class/methods/) — the members an implementation is made of - [Sequence fields on a class](https://osysharp.com/reference/class/collections/) — holding many implementors in a `List` --- # Method overloads > A class can declare several methods with the same name, as long as they differ in their parameter types. Each call picks the one that fits its arguments — by how many, then by their types, then by which parameter type is most specific. A different return type or different parameter names is not a difference, and two methods that differ only that way are a compile error. ## Summary {#summary} Two methods, one name, different parameter types: ```osy title="an overload set" test app=class-overloads class Calc { public decimal Add(decimal a) { return a; } public decimal Add(decimal a, decimal b) { return a + b; } } ``` Each call site picks the one its arguments fit: ```osy title="each call runs its own body" run app=class-overloads [Test] void Each_Call_Picks_Its_Overload() { var c = new Calc(); Assert.Equal(1m, c.Add(1m)); Assert.Equal(3m, c.Add(1m, 2m)); } ``` ## Signature {#signature} ```osy syntax class C { T M(A a) { … } // one overload T M(A a, B b) { … } // another — different parameter COUNT T M(B b) { … } // another — different parameter TYPE } ``` ## Description {#description} ### What makes two overloads different? {#what-differs} **Their parameter types, in order — and nothing else.** Two methods that differ only in return type, or only in parameter names, are the same method declared twice, and that is a compile error: ```osy syntax decimal Add(decimal a) { … } string Add(decimal b) { … } // ✗ same signature — the return type and the name `b` are not differences ``` The reason is that a call site cannot act on either one. `c.Add(1m)` says nothing about what it wants back, and it does not name the parameter, so there would be no way to say which you meant. ### Which overload does a call pick? {#how-a-call-picks} In three steps, stopping as soon as one candidate is left. **1. How many arguments.** Only the overloads that your arguments can bind to survive — counting [default values](https://osysharp.com/reference/class/methods/), which make a parameter optional, and named arguments, which bind by name rather than position. This is usually the whole story: ```osy title="chosen by argument count" run app=class-overloads [Test] void Arity_Decides() { var c = new Calc(); Assert.Equal(5m, c.Add(5m)); // the one-parameter Add Assert.Equal(9m, c.Add(4m, 5m)); // the two-parameter Add } ``` **2. What type they are.** When several overloads take the right number of arguments, the ones whose parameters your arguments actually fit survive: ```osy title="chosen by argument type" test app=class-overloads class Formatter { public string Show(decimal d) { return "number"; } public string Show(string s) { return "text"; } } ``` ```osy title="the type of the argument decides" run app=class-overloads [Test] void Type_Decides() { var f = new Formatter(); Assert.Equal("number", f.Show(1m)); Assert.Equal("text", f.Show("x")); } ``` **3. Which is most specific.** If more than one still fits, the one whose parameter type is *lower in the class hierarchy* wins — `Circle` beats `Shape`: ```osy title="the more specific overload wins" test app=class-overloads class Shape { public string Name; } class Circle : Shape { public decimal Radius; } class Painter { public string Draw(Shape s) { return "shape"; } public string Draw(Circle c) { return "circle"; } } ``` ```osy title="a Circle picks Draw(Circle)" run app=class-overloads [Test] void Most_Specific_Wins() { var p = new Painter(); Assert.Equal("circle", p.Draw(new Circle { Name = "a", Radius = 1m })); } ``` ### It is the DECLARED type that chooses, not the runtime one {#static-not-virtual} This is the one rule worth reading twice, because it differs from how [`override`](https://osysharp.com/reference/class/inheritance/) works. **Which overload runs is decided when your code is compiled, from the type of the variable you are holding.** Which `override` runs is decided while it runs, from the type of the object. ```osy title="the slot decides, not the value" run app=class-overloads [Test] void The_Declared_Type_Chooses() { var p = new Painter(); Shape held = new Circle { Name = "a", Radius = 1m }; Assert.Equal("shape", p.Draw(held)); // held is declared `Shape` — even though it holds a Circle } ``` If you want the object to decide, that is what `virtual`/`override` is for — see [Class inheritance](https://osysharp.com/reference/class/inheritance/). ### Can a subclass add an overload? {#inheritance} A subclass inherits its base's overloads and can add to the set. Declaring a method with a **new** signature adds an overload; declaring one with an **existing** signature overrides it (and must say `override`): ```osy title="one adds, one overrides" test app=class-overloads class Reporter { public virtual string Line(decimal a) { return "base-1"; } } class RichReporter : Reporter { public override string Line(decimal a) { return "rich-1"; } // same signature → an override public string Line(decimal a, decimal b) { return "rich-2"; } // new signature → a sibling overload } ``` ```osy title="both are callable, and the override still dispatches" run app=class-overloads [Test] void Adding_And_Overriding() { var r = new RichReporter(); Assert.Equal("rich-1", r.Line(1m)); Assert.Equal("rich-2", r.Line(1m, 2m)); Reporter asBase = r; Assert.Equal("rich-1", asBase.Line(1m)); // virtual dispatch still finds the override } ``` `base.Line(…)` picks from the base's set the same way, so an override of one overload can still call either. ### When a call is ambiguous {#ambiguous} If two overloads both fit and neither is more specific, the call is refused rather than guessed. Say which you mean by giving the argument a declared type: ```osy syntax class P { string Go(Left? l, Right? r) { … } string Go(Right? r, Left? l) { … } } p.Go(null, null); // ✗ ambiguous — both fit, neither is more specific Left? l = null; p.Go(l, null); // ✓ the declared type of `l` settles it ``` ### A method and a property cannot share a name {#properties} Only methods overload. A property has no overload set to join, so a method named after a property is refused — one of the two has to be renamed. ### Constructors do not overload yet {#constructors} A class declares one [constructor](https://osysharp.com/reference/class/constructors/). Give it the widest parameter list and default the ones a caller may omit: ```osy syntax public Box(decimal width, decimal height = 1m) { … } // one constructor, two ways to call it ``` ## See also {#see-also} - [class methods](https://osysharp.com/reference/class/methods/) — declaring methods, default values, and named arguments - [Class inheritance](https://osysharp.com/reference/class/inheritance/) — `virtual`/`override`, and why they decide at a different moment than overloads do - [constructor](https://osysharp.com/reference/class/constructors/) — the single constructor, and defaulting its parameters - [Classes](https://osysharp.com/reference/class/index/) — what a class is --- # Sequence fields on a class > A class can hold many values in one field — `string[]`, `int[]`, `List`, `HashSet`, `Dictionary`. The element may be a scalar, an enum, or another class; the whole LINQ surface reads it, a `foreach` over a map binds each entry's `Key` and `Value`, and an array is fixed-size exactly as in C#. An entity cannot hold one: a collection member of an entity is a relation. ## Summary {#summary} A `class` field can hold **many values**. Four spellings, all of them C#'s: ```osy title="four ways to hold many values" test app=class-collections class Tag { public string Name; } class Document { public string Title; public string[] Keywords; // fixed-size — its length is part of it public int[] Scores; // any scalar, not just string public List Tags; // growable public HashSet Seen; // distinct, unordered public Dictionary Counts; } ``` ## Signature {#signature} ```osy syntax public T[] Field; // array — fixed-size; indexable, .Count, foreach, LINQ. No .Add public List Field; // list — everything an array does, plus .Add / .Remove / .RemoveAll public HashSet Field; // set — distinct membership; .Add / .Contains / .Remove public Dictionary Field; // map — d[k], .ContainsKey, .TryGetValue, .GetValueOrDefault, .Keys, .Values ``` `T` may be a **scalar** (`string`, `int`, `long`, `decimal`, `double`, `bool`, `Guid`, `DateTime`, …), an **enum** you declared, **another class**, or **another collection** — `Dictionary>` and `List>` are both fine, at any depth. `byte[]` is the exception and is not a sequence at all — it is the binary scalar type. ⚠ The one thing that cannot nest is a **Dictionary KEY**: a key has to be comparable, and a collection is not. The compiler says so rather than storing it and failing later. ## Description {#description} ### Reading one {#reading} Every sequence field answers the same questions, and they are the [LINQ verbs](https://osysharp.com/reference/query/in-memory-linq/) you already use — filter, project, sort, aggregate — evaluated in memory over the values the object holds: ```osy title="the whole LINQ surface, over a field" test app=class-collections int LongKeywords(Document d) { return d.Keywords.Where(k => k.Length > 5).Count; } string FirstAlphabetically(Document d) { return d.Keywords.OrderBy(k => k).First(k => k != ""); } bool EveryScorePasses(Document d) { return d.Scores.All(s => s >= 0); } // `Max` has no zero to fall back on, so over NO scores it answers absent — which is why this returns `int?` // where `Count` above returns `int`. Writing `int` here is a compile error, not a silent 0. int? Best(Document d) { return d.Scores.Max(s => s); } ``` Indexing and `foreach` read it directly, with no ceremony: ```osy title="index it, walk it" test app=class-collections int Total(Document d) { var sum = 0; foreach (var s in d.Scores) { sum = sum + s; } return sum + d.Scores[0]; } ``` ### A collection member starts EMPTY {#starts-empty} A sequence member of a class is an empty collection from the moment the object is made — you never have to check it before adding to it: ```osy syntax class Valley { List trees = new List(); public void Build() { trees.Add(new Prop { X = 1 }); // works on a brand-new Valley } } ``` The initializer above is the natural way to write it and is what most people will. It is not load-bearing: a `List trees;` with no initializer is empty too. Every other reading in the language already treats an absent collection as empty — iterating one yields nothing, `.Count` answers 0, a query over it is empty — so `.Add` agrees with them rather than being the one operation that does not. ### Filling one {#filling} A collection literal fills any of them at construction: ```osy title="build one" test app=class-collections Document New() { return new Document { Title = "notes", Keywords = ["osy", "reference"], Scores = [10, 30, 20] }; } ``` ### Reading a map {#dictionary} `d[k]` reads one entry and **throws when the key is absent**, exactly as in C#. The two total forms are the ones to reach for when a miss is ordinary: ```osy title="reading a key that may not be there" test app=class-collections // `.TryGetValue` — C#'s own spelling, and the value is in scope in the branch. int SeenOrZero(Document d, string word) { if (d.Counts.TryGetValue(word, out var n)) { return n; } return 0; } // `.GetValueOrDefault` — the same question as an expression, so it composes with `??`. int Seen(Document d, string word) { return d.Counts.GetValueOrDefault(word, 0); } ``` ⚠ With **no fallback**, `.GetValueOrDefault(k)` answers **null** on a miss rather than the type's zero. That is a deliberate difference from C#, and it is the useful one: a `0` is indistinguishable from a *stored* `0`, so a miss would be invisible. A null makes you decide. ### Iterating a map {#iterating} **A `foreach` over a map binds each entry as a pair, with `Key` and `Value`** — C#'s own shape: ```osy title="every entry, both halves" test app=class-collections string Summarise(Document d) { var s = ""; foreach (var kv in d.Counts) { s = s + kv.Key + "=" + kv.Value + ";"; } return s; } ``` The same pair is what the **LINQ verbs** filter and project over, so a map is a source like any other sequence: ```osy title="LINQ straight over a map" test app=class-collections int TotalRepeated(Document d) { return d.Counts.Where(kv => kv.Value > 1).Sum(kv => kv.Value); } // `First` answers the PAIR, so its `Key` is one hop away. string Rarest(Document d) { return d.Counts.OrderBy(kv => kv.Value).First(kv => kv.Value > 0).Key; } ``` `.ToList()` and `.ToArray()` both hand you the pairs as a plain sequence. `.Keys` and `.Values` are still there when you only want one half: ```osy title="one half at a time" test app=class-collections int TotalSeen(Document d) { return d.Counts.Values.Sum(); } int HowManyKeys(Document d) { return d.Counts.Keys.Count; } ``` Both are a **snapshot**, not C#'s live view: a `.Values` you already took does not follow a later `.Add`. Take it again when you want the current contents. ### Changing a map {#map-changing} `.Add(k, v)` **throws if the key is taken** — that is exactly what separates it from `d[k] = v`, which overwrites. When you mean "add only if absent", `.TryAdd` says so and answers whether it went in: ```osy title="the three ways to write into a map" test app=class-collections void Record(Document d, string word) { d.Counts[word] = 1; // upsert — replaces whatever was there d.Counts.TryAdd(word, 1); // adds only if absent; answers false if not d.Counts.Remove(word); // answers whether it was there d.Counts.Clear(); // empties it } bool AnyoneAt(Document d, int n) { return d.Counts.ContainsValue(n); // the mirror of .ContainsKey } ``` ### Changing one {#changing} A `List` grows and shrinks with `.Add(x)` and `.Remove(x)`. **`.RemoveAll(x => …)` deletes every match in one go and answers how many went** — it changes the list you called it on, so anything else holding that same list sees the change too: ```osy title="remove every match, in place" test app=class-collections int DropShortTags(Document d) { return d.Tags.RemoveAll(t => t.Name.Length < 3); } ``` That in-place mutation is the difference from `d.Tags.Where(…)`, which answers a **new** sequence and leaves the original alone. Reach for `Where` when you want a filtered view, and `RemoveAll` when the list itself should change. The rest of C#'s vocabulary is there too — `.AddRange(other)` appends every item of another collection, `.Insert(i, x)` places one at a position, and `.Clear()` empties it (on a `List`, a `HashSet` or a `Dictionary`): ```osy title="append, place, empty" test app=class-collections void Reset(Document d, List extra) { d.Tags.AddRange(extra); // append all of them d.Tags.Insert(0, new Tag { Name = "first" }); d.Tags.Clear(); } ``` To ask **where** something sits rather than change anything, `.IndexOf(item)`, `.LastIndexOf(item)` and [`.FindIndex(x => …)`](https://osysharp.com/reference/query/in-memory-linq/) answer its position, or `-1` when it is not there. `IndexOf` finds the first occurrence and `LastIndexOf` the last, which is the only thing they disagree about. Over a list of entity rows all three compare by [row identity](https://osysharp.com/reference/entity/equality/), so `.IndexOf(row)` finds the row without your comparing `.Id`. Because it changes things, a change belongs in an `action` (or an `on-change` body), never in a `render` slot — a render expression is re-evaluated whenever anything it reads changes, in an order nobody controls, so the compiler refuses `.Add` / `.Remove` / `.RemoveAll` there and names where they go instead. The reads (`.Count`, `.Contains`, `.Keys`, `.Values`, indexing, every LINQ verb) are render-slot material and always were. ### A collection inside a collection {#nesting} The grouping shape — a map of lists — is an ordinary field: ```osy title="a map of lists" test app=class-collections-nested class Index { public Dictionary> ByTag; public List> Rows; } int TotalTagged(Index ix) { var n = 0; foreach (var kv in ix.ByTag) { n = n + kv.Value.Count; } return n; } // The inner list is a REAL list — reached through the pair and appended to in place. void Tag(Index ix, string tag, int id) { if (!ix.ByTag.ContainsKey(tag)) { ix.ByTag[tag] = new List(); } ix.ByTag[tag].Add(id); } ``` ### An enum element {#enums} An element may be an **enum you declared**, in any of the four spellings — including both slots of a map, which is how a per-status tally is written: ```osy title="collections of an enum" test app=class-collections-enum enum Status { Open, Closed } class Board { public List Lanes; public Status[] Order; public Dictionary Tally; // an enum KEY public Dictionary ByName; // an enum VALUE } int OpenCount(Board b) { var n = 0; foreach (var s in b.Lanes) { if (s == Status.Open) { n = n + 1; } } return n; } int OpenTally(Board b) { return b.Tally.Where(kv => kv.Key == Status.Open).Sum(kv => kv.Value); } ``` ### Array or list? {#array-or-list} Use a **`List`** when the contents change — it is what you will want most of the time. Use a **`T[]`** when the set of values is settled once and then only read. The difference is C#'s and the compiler holds you to it: an array's length is part of the type, so it has no `.Add`: ```osy syntax d.Keywords.Add("x"); // ✗ `Add` needs a growable collection, and `string[]` is fixed-size d.Tags.Add(tag); // ✓ a List grows ``` Nothing else differs. Both are indexable, both count, both `foreach`, both answer every LINQ verb — so choosing an array never costs you a way to read it. ### Can an entity hold a list? {#entities} This is a `class` surface, and deliberately. On an [entity](https://osysharp.com/reference/entity/declaration/) a collection member means something else entirely: `OrderLine[] Lines` is a **relation** — a set of child ROWS, stored in their own table and reached through a foreign key. A column cannot hold a list, so `string[] Tags;` on an entity is refused, and it names the two real answers: - **Model each value as a row.** A `DocumentTag` entity holding one `string`, reached as `[ForeignKey(Document)] DocumentTag[] Tags;` — which is queryable, indexable, and the answer whenever you will ever want to search or count by it. - **Or keep the list on a `class`**, when it is a value the row simply carries and nobody queries across. See [relations](https://osysharp.com/reference/entity/relations/) for the relation form. ## See also {#see-also} - [LINQ over a local list](https://osysharp.com/reference/query/in-memory-linq/) — the verbs that read these fields, and the same verbs over a local sequence - [class properties](https://osysharp.com/reference/class/properties/) — a member that runs a body on access - [relations](https://osysharp.com/reference/entity/relations/) — what a collection member means on an entity, and why it is a different thing --- # Testing which class a value is > `s is Circle` asks which type a value actually is at run time, answering by the value's own type rather than the type it is declared as. A derived value satisfies its base, `null` is of no type, and `is not` negates the test. `OfType()` asks the same question of a whole set, keeping the elements that are a `T` and re-typing them. `(T)value` and `value as T` convert to the narrower type — failing loudly, or answering null. ## Summary {#summary} `is` asks what a value **actually** is, which is not always what it is declared as: ```osy title="asking which shape it is" test app=class-type-test class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string WhatIsIt() { Shape s = new Circle { Name = "c", Radius = 2m }; if (s is Circle) { return "circle"; } return "shape"; } ``` The slot says `Shape`; the value is a `Circle`, and `is` answers by the value. ## Signature {#signature} ```osy syntax value is Class // true when the value's runtime type is Class, or derives from it value is not Class // the negation ``` ## Description {#description} ### It answers by the RUNTIME type {#runtime-type} That is the whole point — a declared type is what the compiler knows, and `is` is for what the compiler cannot know. A value that really is a plain `Shape` answers false: ```osy title="the test discriminates" test app=class-type-test-negative class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string WhatIsIt() { Shape s = new Shape { Name = "plain" }; if (s is Circle) { return "circle"; } return "shape"; } ``` ### A derived value satisfies its base {#derived} `is Shape` accepts the whole subtree beneath `Shape`, not only an exact `Shape`. This is what makes it a *type test* rather than a comparison of labels: ```osy title="a Circle IS a Shape" test app=class-type-test-derived class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string Check() { Shape s = new Circle { Name = "c", Radius = 2m }; if (s is Shape) { return "yes"; } return "no"; } ``` ### `null` is of no type {#null} As in C#, `null` is not an instance of anything — so `null is Circle` is false, and `null is not Circle` is true: ```osy title="null satisfies no type test" test app=class-type-test-null class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string Check() { Shape? s = null; if (s is not Circle) { return "not-a-circle"; } return "circle"; } ``` ### Narrowing a whole collection — `OfType()` {#oftype} `OfType()` keeps the elements that are a `T` and gives you them **as** a `T`: ```osy title="a mixed list narrowed to one type" test app=class-type-test-oftype class Shape { public string Name; } class Circle : Shape { public decimal Radius; } decimal TotalRadius() { List shapes = new List(); shapes.Add(new Circle { Name = "a", Radius = 1m }); shapes.Add(new Shape { Name = "b" }); shapes.Add(new Circle { Name = "c", Radius = 3m }); decimal total = 0m; foreach (var c in shapes.OfType()) { total = total + c.Radius; } return total; // 4 — the plain Shape is not in the set } ``` It does two things at once, and the second is why you would reach for it over `Where`: it **filters** to the elements that really are a `Circle`, and it **re-types** them, so `c.Radius` reads. `shapes.Where(s => s is Circle)` filters identically but its result is still a `List` statically, so a derived field is out of reach. It only ever narrows. Asking for the element's own base, or for a type outside its hierarchy, is refused rather than quietly widening the read or returning nothing. ### Converting to the narrower type — cast or `as`? {#cast-and-as} A type test answers *whether*; a **conversion** hands you the value at the narrower type. Two spellings, differing only in what happens when the value is not that type: ```osy title="the cast and its try-conversion" test app=class-type-test-cast class Shape { public string Name; } class Circle : Shape { public decimal Radius; } decimal RadiusOrZero(Shape s) { Circle? maybe = s as Circle; // null when it is not a Circle if (maybe == null) { return 0m; } return maybe.Radius; } decimal RadiusOf(Shape s) { Circle c = (Circle)s; // FAILS when it is not a Circle return c.Radius; } ``` | | when it IS the type | when it is NOT | |---|---|---| | `(Circle)s` | the value, typed `Circle` | **fails**, naming both types | | `s as Circle` | the value, typed `Circle?` | `null` | Use the cast when being wrong is a bug you want to hear about, and `as` when "not a Circle" is an ordinary case you are about to handle. That is the same advice C# gives, for the same reason. **`null` converts to `null` under both, and neither fails.** A cast of null is not a failed cast — there is nothing there to be of the wrong type. Widening needs no conversion at all: a `Circle` already goes wherever a `Shape` is expected ([[class-inheritance#upcast]]). ### Dispatching on the type — `switch` {#switch} A `switch` arm can be a **type pattern** — `Circle c =>` — binding the value at that arm's own type: ```osy title="one arm per type" test app=class-type-test-switch class Shape { public string Name; } class Circle : Shape { public decimal Radius; } string Describe() { Shape s = new Circle { Name = "c", Radius = 2m }; return s switch { Circle c => "circle:" + c.Radius.ToString(), // `c` is a Circle here Shape p => "shape:" + p.Name, }; } ``` The binding is **required** — write `Circle c =>`, not `Circle =>`. A bare name in pattern position is already an enum member, and the binding is what tells the two apart. #### Every type must be handled {#exhaustive} A `switch` with no `_` arm must have an arm for **every** type in the hierarchy. Leave one out and the app does not compile, and the message names what is missing: ```osy syntax return s switch { Circle c => "circle", // ERROR: does not handle every 'Shape' — 'Shape' has no arm }; ``` This is stricter than C#, which only warns — and deliberately so. C#'s compiler cannot see hierarchies that other assemblies might extend, so it cannot know the set is complete. An Osy# app compiles as **one unit**, so the set of types *is* known. What that buys you is the useful half: **adding a type breaks every place that has to decide about it**, instead of those places silently taking a default that was never considered. Add `_ => …` when the rest really are the same — that says so explicitly, and it is not second-best. ### It works the same in the browser {#both-sides} A type test is decided identically wherever the code runs — in a function on the server, in a component in the browser, and across a suspension that starts on one side and resumes on the other. There is no rule to learn about where you may write it. ### Entities test their type too {#entities} `is` works on an [entity hierarchy](https://osysharp.com/reference/entity/inheritance/) as well, and reads the same. The two are decided by different means — an entity is a row and carries its type in a column, which is what lets an entity's test run inside a database query — but nothing about writing one differs. ## Errors {#errors} | you wrote | what you get | |---|---| | `x is Unrelated`, where the two share no hierarchy | refused — no value can be both, so the answer would be a constant you did not write | | `x is Solo`, where `Solo` has no base and no subtypes | refused — a type test is only meaningful inside a hierarchy | | `(Circle)s` where `s` is not a `Circle` | fails at run time, naming both types and pointing at `is` / `as` | | `(Circle)s` where the two share no hierarchy | refused at compile time — no value can be both | | `(Contract)order` between two ENTITY types | refused — a row already carries its type; narrow the READ with `OfType` | | `xs.OfType()` where `Circle` does not derive from the element type | refused — no element of the set could be one | | `xs.OfType()` where `Shape` is the element's BASE | refused — that would WIDEN the read, not narrow it | ## See also {#see-also} - [Class inheritance](https://osysharp.com/reference/class/inheritance/) — declaring the hierarchy a type test asks about - [entity Sub : Base](https://osysharp.com/reference/entity/inheritance/) — the same question asked of rows - [Classes](https://osysharp.com/reference/class/index/) — what a class is --- # `params` parameters > `params` lets a method be called with any number of trailing arguments — `Total(1m, 2m, 3m)` — which arrive as one array. It must be the last parameter and its type must be an array. Calling with no trailing arguments passes an empty array, so a `params` parameter is optional without a default; passing an actual array of the right type still binds directly, without being wrapped again. ## Summary {#summary} `params` collects the trailing arguments into an array: ```osy title="any number of arguments" run app=class-params class Calc { public decimal Total(params decimal[] xs) { decimal t = 0m; foreach (var x in xs) { t = t + x; } return t; } } [Test] void Params_Collects_The_Trailing_Arguments() { var c = new Calc(); Assert.Equal(6m, c.Total(1m, 2m, 3m)); Assert.Equal(0m, c.Total()); // no trailing arguments — an EMPTY array, not null } ``` ## Signature {#signature} ```osy syntax (params [] ) { … } ( , params [] ) { … } ``` ## Description {#description} ### Where can `params` go, and what type must it be? {#rules} Two rules, both C#'s, and both following from what `params` does — it collects *the rest*: ```osy title="✗ the three ways params is written wrong" syntax decimal Sum(params decimal[] xs, string tail) { … } // ✗ it must be the LAST parameter decimal Sum(params decimal x) { … } // ✗ its type must be an ARRAY decimal Sum(params decimal[] xs = null) { … } // ✗ it is already optional; no default ``` A parameter before it is ordinary and keeps its own argument: ```osy title="a fixed parameter, then the rest" run app=class-params class Report { public decimal Offset(decimal start, params decimal[] xs) { decimal t = start; foreach (var x in xs) { t = t + x; } return t; } } [Test] void The_Leading_Parameter_Keeps_Its_Own_Argument() { var r = new Report(); Assert.Equal(103m, r.Offset(100m, 1m, 2m)); } ``` ### Passing an array directly still works {#an-actual-array} If you already have the array, pass it — it binds to the parameter as-is rather than being wrapped in another array: ```osy title="an array binds directly" run app=class-params [Test] void An_Actual_Array_Is_Not_Wrapped_Again() { var c = new Calc(); decimal[] values = [4m, 5m]; Assert.Equal(9m, c.Total(values)); // one array of two — not one array containing one array } ``` Which of the two readings applies is decided by the argument's **type**, not by how many arguments there are — both spellings pass exactly one. A `decimal[]` is the array; a `decimal` is one element of it. ### `params` and overloads {#overloads} A `params` method takes part in [overload resolution](https://osysharp.com/reference/class/overloads/) like any other, with one rule: the ordinary reading is tried first for every candidate, and the collecting form is considered only if nothing matched ordinarily. That has a consequence worth relying on: **adding `params` to an existing method cannot change which overload an existing call already picks.** It can only make a call compile that did not before. ```osy title="an exact match wins over collecting" run app=class-params class Fmt { public string Of(decimal d) { return "one"; } public string Of(params decimal[] ds) { return "many"; } } [Test] void The_Ordinary_Reading_Is_Tried_First() { var f = new Fmt(); Assert.Equal("one", f.Of(1m)); // the exact single-argument method Assert.Equal("many", f.Of(1m, 2m)); // only the collecting one can take two } ``` `params` is **not** part of a method's identity, so `Sum(params decimal[])` and `Sum(decimal[])` are the same method and cannot both be declared — a call site could not tell them apart. ### What is the collected array, inside the body? {#no-new-shape} Inside the body, `rest` is an ordinary array: `foreach` over it, ask for its `Count()`, index it, pass it on. There is nothing to learn beyond the call form. ## See also {#see-also} - [class methods](https://osysharp.com/reference/class/methods/) — methods, and the member-body surface - [Method overloads](https://osysharp.com/reference/class/overloads/) — how a call site picks from a set of same-named methods - [`static` methods](https://osysharp.com/reference/class/static/) — `static`, which combines with `params` freely - [Classes](https://osysharp.com/reference/class/index/) — fields, `const`, and what a class is --- # `readonly` fields > A `readonly` field can be assigned only where it is declared or in a constructor of the class that declares it. Everywhere else — a method of the same class, a subclass constructor, an object initializer, any code holding the value — a write is a compile error. The field itself is ordinary: it holds a per-instance value chosen at construction, unlike a `const`, whose value is fixed when the code is compiled. ## Summary {#summary} `readonly` marks a field that only the constructor may set: ```osy title="a field the constructor fixes" test app=class-readonly class Booking { public readonly string Reference; public readonly int Seats; public Booking(string reference, int seats) { Reference = reference; Seats = seats; } } ``` Once the object exists, the field is settled — every other write is refused at compile time. ## Signature {#signature} ```osy syntax readonly T Name; // set by a constructor readonly T Name = value; // set at the declaration public readonly T Name; // combines with any visibility ``` ## Description {#description} ### The two places a `readonly` field may be assigned {#where} There are exactly two, and they are the same two as in C#: 1. **its own declaration** — `public readonly decimal Rate = 0.25m;` 2. **a constructor of the class that declares it** ```osy title="both legal writes" test app=class-readonly class Invoice { public readonly decimal Rate = 0.25m; // 1. at the declaration public readonly string Number; public Invoice(string number) { Number = number; // 2. in the constructor } } ``` Both values are ordinary per-instance data — read them like any other field: ```osy title="a readonly field holds a normal runtime value" run app=class-readonly [Test] void ReadOnly_Fields_Hold_Their_Values() { var i = new Invoice("INV-1"); Assert.Equal("INV-1", i.Number); Assert.Equal(0.25m, i.Rate); } ``` ### Assigning it anywhere else is a compile error {#refused} The refusals are the feature. None of these compile: ```osy syntax var i = new Invoice("INV-1"); i.Number = "INV-2"; // ✗ a write from outside i.Rate += 0.1m; // ✗ `+=` is a write too var j = new Invoice { Number = "x" }; // ✗ an object initializer runs after the constructor class Invoice { public void Renumber(string n) { Number = n; // ✗ a METHOD of the same class — only a constructor may write } } ``` The last one is worth pausing on: `readonly` narrows the write to **constructors**, not to the class. A method of the declaring class is refused exactly like outside code. ### A subclass constructor cannot write the base's field {#inheritance} A field belongs to the class that declares it. By the time a derived constructor's body runs, the base has already been constructed and its `readonly` fields are settled — so a subclass may write its **own** readonly fields and not its base's: ```osy title="each class writes the fields it declares" test app=class-readonly class Badge { public readonly string Tag; public Badge(string tag) { Tag = tag; } } class Ranked : Badge { public readonly decimal Rank; public Ranked(string tag, decimal rank) : base(tag) { Rank = rank; // its own — fine } } ``` Writing `Tag = "x"` inside `Ranked`'s constructor is a compile error: pass the value to `base(…)` instead, which is what the example does. ### `readonly` is not `const` {#versus-const} They read similarly and mean different things: | | `const` | `readonly` | |---|---|---| | when the value is chosen | when the code is compiled | when the object is constructed | | can it differ per instance | no — there is one value | yes — each `new` may pass a different one | | what it may be initialized with | a compile-time constant | any expression the constructor can evaluate | | is there a per-instance slot | no, uses are replaced by the value | yes, it is a real field | Reach for `const` for a fixed number or name the whole program shares, and `readonly` for a value each instance is given once and then keeps. Writing both on one field is a compile error — a `const` has no instance slot to protect. ### `readonly` applies to a field, not a property {#not-a-property} A property has no storage of its own, so there is nothing for `readonly` to narrow. The property spellings that mean the same things are: - `{ get; }` — an [auto-property](https://osysharp.com/reference/class/properties/) only a constructor may set - `{ get; init; }` — settable during construction, including from an object initializer ```osy syntax public readonly decimal Area { get; set; } // ✗ readonly applies to a FIELD public decimal Area { get; } // ✓ only the constructor sets it public decimal Area { get; init; } // ✓ an object initializer may too ``` ### Can an entity field be `readonly`? {#entities} `readonly` is a `class` modifier. An entity's fields are stored rows written by data operations, and what may write them is declared in its `security { }` block rather than by a member modifier. ## See also {#see-also} - [class properties](https://osysharp.com/reference/class/properties/) — `init`, `required`, and the property forms that express single-assignment - [constructor](https://osysharp.com/reference/class/constructors/) — the constructor, which is where a `readonly` field gets its value - [Classes](https://osysharp.com/reference/class/index/) — fields, defaults, and what a class is - [type visibility (public / internal)](https://osysharp.com/reference/types/visibility/) — `public`, `private` and `protected`, which combine with `readonly` --- # `static` methods > A `static` method belongs to the type rather than to any instance, and is called on the type name — `Money.Round(x)`. It has no `this`, so it cannot read the class's instance fields; it can call the class's other static methods and read its `const` values by bare name. Fields cannot be static: a `const` covers the fixed values, and anything that would need to change belongs to an instance or to an entity. ## Summary {#summary} A `static` method is called on the type, not on a value: ```osy title="a static method, called on the type name" test app=class-static class Money { public decimal Amount; public static decimal Round(decimal value) { return Math.Round(value, 2); } } decimal RoundAPrice() { return Money.Round(19.999m); // on the TYPE — there is no Money instance here } ``` Reach for it when the operation is about the type but not about any particular value of it — a conversion, a validation, a calculation over its arguments. ## Signature {#signature} ```osy syntax static () { … } public static () { … } ``` `static` goes after the visibility word, as in C#. It applies to methods only. ## Description {#description} ### A static method has no `this` {#no-this} That is the whole of the rule, and everything else follows from it. There is no instance, so there is nothing for an instance field to be read from: ```osy title="✗ a static method reaching for instance state" syntax class Money { public decimal Amount; public static decimal Doubled() { return Amount * 2m; // ✗ 'Amount' belongs to an INSTANCE } public static decimal Half() { return this.Amount / 2m; // ✗ `this` has no meaning in a static method } } ``` Take the value as a parameter instead — which is usually what the method wanted anyway: ```osy title="pass in what the method needs" test app=class-static class Tax { public static decimal Net(decimal gross, decimal rate) { return gross / (1m + rate); } } ``` ### What a static method CAN see of its own class {#what-it-sees} Its other static methods and its `const` values, both by bare name — the same rule as C#: ```osy title="statics reach statics, and consts, unqualified" run app=class-static class Rate { public const decimal Standard = 0.25m; public static decimal Apply(decimal amount) { return amount * (1m + Standard); // a const, by bare name } public static decimal ApplyTwice(decimal amount) { return Apply(Apply(amount)); // another static, by bare name } } [Test] void Statics_Reach_Statics_And_Consts() { Assert.Equal(125m, Rate.Apply(100m)); Assert.Equal(156.25m, Rate.ApplyTwice(100m)); } ``` An **instance** method may call its class's static methods the same way — it simply does not pass its `this` along: ```osy title="an instance method calling its type's static" test app=class-static class Line { public decimal Gross; public decimal Net() { return Tax.Net(Gross, 0.25m); } } ``` ### Call it on the type, never through a value {#call-form} The two directions are both compile errors, and each says which spelling to use: ```osy syntax var m = new Money { Amount = 1m }; m.Round(2.5m); // ✗ 'Money.Round' is static — call it as `Money.Round(…)` Money.Amount; // ✗ 'Money.Amount' is an instance member — access it through an instance ``` Refusing the first is C#'s rule too, and it is worth the strictness: `m.Round(…)` reads as though the method can see `m`, and it cannot — the receiver would be evaluated and discarded. ### Statics inherit {#inheritance} A static method declared on a base class is callable on a derived one, like any other inherited member: ```osy title="a subclass inherits its base's statics" test app=class-static class Shape { public string Name; public static decimal Zero() { return 0m; } } class Circle : Shape { public decimal Radius; } decimal ZeroThroughTheSubclass() { return Circle.Zero(); // Shape declares it; Circle inherits it } ``` It cannot be `virtual`, `override` or `abstract`, and combining them is a compile error. Those words choose a body from the *receiver's* runtime type, and a static call has no receiver to choose by. ### Static methods overload {#overloads} Exactly like instance methods — a name maps to a set, and the call site picks by the arguments. See [Method overloads](https://osysharp.com/reference/class/overloads/) for the rule. ```osy title="two statics sharing a name" test app=class-static class Fmt { public static string Of(decimal d) { return d.ToString(); } public static string Of(decimal d, string unit) { return d.ToString() + " " + unit; } } ``` ### Fields cannot be static {#no-static-fields} `static` applies to methods only. A static **field** would be mutable state shared by every application running in the host process, with no per-app copy to reset — so it is refused, in as many words: ```osy syntax class Counter { public static decimal Total; // ✗ cannot be `static` } ``` There are three things people reach for it for, and each has its own answer: | what you want | reach for | |---|---| | a fixed value the whole program shares | `const` — already static, and needs no modifier | | a value that belongs to one object | an ordinary field | | state that outlives a request | an `entity` — stored, per-app, and secured | For the same reason there is no static **constructor**: it would exist to initialize static state, and there is none. ## See also {#see-also} - [class methods](https://osysharp.com/reference/class/methods/) — instance methods, and the member-body surface a static method shares - [Method overloads](https://osysharp.com/reference/class/overloads/) — how a call site picks from a set of same-named methods - [Classes](https://osysharp.com/reference/class/index/) — fields, `const`, and what a class is - [type visibility (public / internal)](https://osysharp.com/reference/types/visibility/) — `public`, `private` and `protected`, which combine with `static` --- # class methods > Behaviour attached to a class — a method with a receiver, called as value.Method(). Classes are in-memory values, so a method is the natural place for logic that belongs to a shape rather than to the database. ## Summary {#summary} A `class` may declare **methods**, called on a value: `cart.Total()`. A method has a receiver — the instance it was called on — and can read and write that instance's fields. Use a method when the logic belongs to the *shape*. Use a [function](https://osysharp.com/reference/function/declaration/) when it belongs to the application. ## Signature {#signature} ```osy syntax class { public ; public () { … } // reads/writes this instance's fields } ``` ## Description {#description} ### A method reads its own fields {#fields} Inside a method the class's fields are in scope by name — there is no ceremony: ```osy title="a class that can total itself" test app=class-methods class Line { public string Sku; public int Qty; public decimal UnitPrice; public decimal Total() { return Qty * UnitPrice; } } decimal LineTotal(string sku, int qty, decimal price) { var line = new Line { Sku = sku, Qty = qty, UnitPrice = price }; return line.Total(); } ``` ### A method can mutate the instance {#mutation} A class is an in-memory value, so a method may change it. Nothing is persisted — there is no row behind it: ```osy title="a method that changes the value" test app=class-methods class Basket { public decimal Total; public int Count; public void Add(decimal amount) { Total = Total + amount; Count = Count + 1; } public decimal Average() { return Count == 0 ? 0m : Math.Round(Total / Count, 2); } } decimal AverageOfThree(decimal a, decimal b, decimal c) { var basket = new Basket { }; basket.Add(a); basket.Add(b); basket.Add(c); return basket.Average(); } ``` ### Can a component hold one as state? {#component-state} A component field can hold a class instance, and its methods are callable from the component's actions and lifecycle hooks like any other value. This is how a small piece of behaviour — a gate, a counter, a tiny state machine — lives beside the page that uses it rather than being spread across loose fields. The worked example is a **cooldown**: "don't do this again until N has passed", which has no cadence of its own and so is not what [on every](https://osysharp.com/reference/ui/cadence/) is for. ```osy title="a cooldown gate, held as component state" test app=class-methods-component class Cooldown { public DateTime ReadyAt; /// True once the wait has passed — then `Arm` starts the next one. public bool Ready() { return DateTime.UtcNow >= ReadyAt; } public void Arm(TimeSpan wait) { ReadyAt = DateTime.UtcNow + wait; } } [Page("/cooldown")] [AllowAnonymous] component Repeater() { // Ready immediately — a field is required by default, so it is given a value at the create site. Cooldown gate = new Cooldown { ReadyAt = DateTime.UtcNow }; int fired = 0; action Nudge() { // Held down, this fires at most once every 90ms rather than once per event. if (gate.Ready()) { fired = fired + 1; gate.Arm(TimeSpan.FromMilliseconds(90)); } } render { Stack(gap: 2) { Text($"fired {fired}"); Pressable("nudge", onClick: Nudge); } } } ``` Reading a field (`gate.ReadyAt`), assigning one (`gate.ReadyAt = …`) and calling a method (`gate.Ready()`) all work on such a field. The instance is ordinary component state: it lives as long as the component does, and it is not persisted. ### Method or function? {#method-or-function} | | class method | top-level function | |---|---|---| | Has a receiver | **yes** — the instance it is called on | no | | Called as | `value.Method()` | `Method(value)` | | Can write rows | no — a class has no table | **yes** | | Good for | logic that belongs to a shape | logic that belongs to the app | An [entity](https://osysharp.com/reference/entity/declaration/) cannot have methods: an entity body holds data, and the behaviour that acts on it is a top-level function. That split is deliberate — it keeps the thing that is persisted separate from the thing that is merely computed. ## See also {#see-also} - [Method overloads](https://osysharp.com/reference/class/overloads/) — declaring several methods with one name, and how a call picks between them - [on every](https://osysharp.com/reference/ui/cadence/) — `on every`, for behaviour that repeats on a clock rather than waiting to be asked - [constructor](https://osysharp.com/reference/class/constructors/) — building an instance with arguments - [function](https://osysharp.com/reference/function/declaration/) — behaviour that belongs to the application, not to a shape - [entity](https://osysharp.com/reference/entity/declaration/) — why an entity has no methods --- # class properties > A class member that reads and writes like a field but runs a body on access — a computed value, a validating setter, or an auto-property whose storage the platform synthesizes. It is a method dressed as a field access, so it works everywhere a class does: server, client, and across a suspension. ## Summary {#summary} A `class` may declare **properties** — members that read and write like a field but run a body on access. A property is the natural home for a value *derived* from other fields (`Label`), for a write that must be *validated* or *transformed*, and for a field you want to expose with asymmetric access. It is, exactly as in C#, a pair of methods dressed as a field: a read `obj.Prop` runs the getter, a write `obj.Prop = v` runs the setter. Use a plain [field](https://osysharp.com/reference/class/methods/) when a value is just stored; reach for a property when *access* itself is behaviour. ## Signature {#signature} ```osy syntax class { public => ; // computed — read-only, no storage public { get => ; } // getter-only, explicit public { get => …; set => …; } // full property over a backing field (`value` is the input) public { get; set; } // auto-property — the platform synthesizes the backing field public { get; private set; } // asymmetric — read anywhere, write only inside the class public { get; init; } // init-only — settable during construction, then frozen public required { get; set; } // required — must be supplied in every `new T { … }` } ``` ## Description {#description} ### A computed property — a value derived from other fields {#computed} The smallest property is **getter-only**: an expression over the instance's other fields, with no storage of its own. Written `=> expr`, it recomputes on every read. ```osy title="a value derived from other fields" test app=class-properties class Money { public decimal Amount; public string Currency; // computed on read — no backing storage public string Label => Amount.ToString("F2") + " " + Currency; } ``` Reading it runs the getter over the current field values: ```osy title="the getter runs on read" run app=class-properties [Test] void Label_Runs_The_Getter() { var m = new Money { Amount = 9.5m, Currency = "USD" }; Assert.Equal("9.50 USD", m.Label); } ``` A computed property is read-only — it has no setter, so a write to it is a compile error. That is the point: it is a view of other state, not a slot you can assign. ### A full property — a getter and a setter over a backing field {#get-set} When a write needs to be *validated* or *transformed*, give the property both accessors over an explicit private field. Inside the setter, the incoming value is the implicit parameter `value`: ```osy title="a validating setter over a backing field" test app=class-properties class Account { private decimal _rate; public decimal Rate { get => _rate; set { if (value < 0m) { throw "rate cannot be negative"; } _rate = value; } } } ``` A write runs the setter; a read runs the getter: ```osy title="the setter runs on write, the getter on read" run app=class-properties [Test] void Rate_RoundTrips_Through_The_Accessors() { var a = new Account(); a.Rate = 0.2m; Assert.Equal(0.2m, a.Rate); } ``` A bad write — `a.Rate = -1m` — runs the setter body and throws, exactly as the setter says. The setter is the one place the rule lives, so no caller can slip an invalid value past it. ### An auto-property — the platform synthesizes the storage {#auto} When the accessors would be trivial — read the field, write the field — write `{ get; set; }` and the platform synthesizes the hidden backing field for you: ```osy title="an auto-property" test app=class-properties class Contact { public string Name { get; set; } public string Email { get; set; } } ``` It stores and reads a value like a field — both through assignment and through an object initializer: ```osy title="an auto-property stores a value" run app=class-properties [Test] void Auto_Property_Stores_A_Value() { var c = new Contact { Name = "Ada", Email = "ada@example.com" }; Assert.Equal("Ada", c.Name); c.Name = "Grace"; Assert.Equal("Grace", c.Name); } ``` ### Asymmetric visibility — read anywhere, write only inside {#asymmetric} A `private set` narrows the *write* path without touching the read path: anyone can read the property, but only the class's own code can set it. It reuses the same private-member rule as a private method. ```osy title="read anywhere, write only inside the class" test app=class-properties class Ledger { public decimal Balance { get; private set; } // in-class code sets it through the private setter public void Credit(decimal amount) { Balance = Balance + amount; } } ``` From outside `Ledger`, `ledger.Balance = 100m` is a compile error — the setter is private — while `ledger.Balance` reads freely. A bare `{ get; }` behaves the same way: settable inside the class, read-only to the outside. ### `init` — settable only during construction {#init} An `init` accessor is a setter you may run **only while the object is being built** — in an object initializer or the constructor — and never after. It is how you make a value that is fixed once constructed: ```osy title="a value fixed at construction" test app=class-properties class Booking { public string Reference { get; init; } public int Seats { get; init; } } ``` Set it in the object initializer; a write afterwards is a compile error: ```osy title="init is set at construction, then frozen" run app=class-properties [Test] void Init_Is_Set_At_Construction() { var b = new Booking { Reference = "BK-1", Seats = 2 }; Assert.Equal("BK-1", b.Reference); Assert.Equal(2, b.Seats); } ``` Writing `b.Reference = "BK-2"` **after** construction does not compile — the accessor is init-only. Reach for `init` when a field must be supplied when the object is made but must not change once it exists. A bodied `init { … }` runs its body during construction, so it can validate or transform the incoming value exactly like a `set`. ### `required` — must be supplied at every `new` {#required} Marking a member `required` makes the compiler insist it appears in **every** object initializer — a missing one is a compile error, not a value silently left null: ```osy title="a member the caller must supply" test app=class-properties class Registration { public required string Email { get; set; } public string? Name { get; set; } // optional (reads back null when unset) — a bare `string Name` would itself be required } ``` ```osy title="required is enforced at the call site" run app=class-properties [Test] void Required_Is_Supplied() { var r = new Registration { Email = "ada@example.com" }; // Name is optional; Email is required Assert.Equal("ada@example.com", r.Email); } ``` Omitting `Email` — `new Registration { }` — is a compile error. `required` pairs naturally with `init` for a value that must be given once and then frozen: `public required string Email { get; init; }`. A constructor that always sets a required member takes over that obligation **automatically** — the compiler sees the constructor sets it, so `new T(args)` needs no initializer for it and no annotation: ```osy title="a constructor that satisfies required" test app=class-properties class Membership { public required string Owner { get; set; } public Membership(string owner) { Owner = owner; } // sets Owner on every path — the compiler infers it } ``` ```osy title="the constructor satisfies the requirement" run app=class-properties [Test] void Ctor_Satisfies_Required() { var m = new Membership("Ada"); // no `{ Owner = … }` needed — the ctor sets it Assert.Equal("Ada", m.Owner); } ``` The inference is sound and conservative: the constructor must set the member **unconditionally** — directly, or through a method it calls. If it only sets the member inside an `if`/loop, that isn't provable, so the initializer is still required. A constructor that sets *some* required members can leave the rest to the caller's initializer (`new Membership(owner) { OtherRequired = … }`). You may still write `[SetsRequiredMembers]` explicitly — it is accepted and means exactly this. ### A member that lives in the browser {#client-handles} A class may hold the values that only exist on the client — the ones a drawing app builds and keeps: ```osy syntax class Valley { Mesh ground; // geometry, on the GPU Mesh hill; Gradient sky; // a fill the 2D context owns Surface stars; // an offscreen canvas Random rng; // a random stream public void Build() { ground = Mesh.Plane(160, 40); } public void Paint() { Draw.Mesh(ground, 0, 0, 0, "#79b85c"); } } ``` ⭐ **This is what lets a drawing app be organised at all.** A class method can run the `Draw.*` verbs, so each part of a scene can own its own geometry and know how to paint itself, in its own file — and the page is left with what only it knows: the physics, the input, the score. ⚠️ **On a `class`, not on an `entity`.** These values live in the browser, so there is nothing for a stored row to hold; declaring one on a persisted `entity` is refused, and the message says so. ### It runs on the client too {#client} A property is a method call underneath, so it rides the same path a [method](https://osysharp.com/reference/class/methods/) does: a getter read or setter write inside a `[Render(CSR)]` component action runs **in the browser**, with no server round trip, as long as its body is client-runnable. Nothing extra is needed — the accessor ships with the component. ## See also {#see-also} - [`readonly` fields](https://osysharp.com/reference/class/readonly/) — `readonly` fields, the field-level counterpart to `{ get; }` and `init` - [class methods](https://osysharp.com/reference/class/methods/) — behaviour with a receiver; a property is a field-shaped pair of these - [constructor](https://osysharp.com/reference/class/constructors/) — set up an instance's fields (and back an auto-property) at construction - [Classes](https://osysharp.com/reference/class/index/) — the whole `class` surface: fields, constructor, methods, properties - [type visibility (public / internal)](https://osysharp.com/reference/types/visibility/) — `public`/`private` on members, and why a class defaults to `internal` --- # constructor > A class declares one constructor — its name is the class name, it takes no return type, and it runs when you write new T(args). The constructor body runs first; object initializers { Member = value } apply after it; new T(args) evaluates to the constructed object. ## Summary {#summary} A **constructor** initializes a `class` instance. It is declared as a member whose name is the class name and which has **no return type**; you invoke it with `new T(args)`. The constructor **body runs first**, then any object initializers `{ Member = value }` are applied **on top** (so an initializer wins over a value the body set). `new T(args)` evaluates to the constructed object. ## Signature {#signature} ```osy syntax class T { public T( p1, p2 = ) { // no return type // may read the params and assign this fields } public T() : this(, ) { … } // another one, chaining to the first } new T(a, b) // run the constructor these arguments select new T(a, b) { Note = "x" } // …then apply the initializer ``` ## Description {#description} - **A class may declare several constructors**, told apart by their parameter TYPES exactly as [methods](https://osysharp.com/reference/class/overloads/) are — `new T(args)` picks the one its arguments fit. Two that differ only in parameter NAMES are the same constructor declared twice, and a compile error. The name is the class name and there is **no return type** (a `return;` with a value is a compile error). - **`: this(…)` chains to another constructor of the same class**, which runs FIRST — so shared setup lives in one place. The chained-to constructor is the one that runs `: base(…)`; a chaining constructor does not also run the base's, so a base constructor runs exactly once. A chain that comes back round to where it started is a compile error rather than unbounded recursion at construction time. - **Visibility** follows the class-member rule: `public` makes it callable from anywhere; a bare (unmarked) constructor is **private** — callable only from within its own class (the factory-method pattern). - **`new T(args)`** binds the arguments to the constructor's parameters (positional or `name: value`, with C# default-parameter values for omitted optionals), runs the body with the fresh instance in scope, and produces that instance. - **Initializers run after the body**: `new T(args) { Member = value }` runs the constructor first, then assigns each initializer — so an initializer overrides whatever the constructor set for that member (C# order). Initializer values cannot reference the object being constructed. - **A class with no declared constructor** uses the implicit default: `new T()` and `new T { … }` build the instance with no user code. Passing arguments to such a class is a compile error. - **A field initializer runs before every constructor body** (`decimal Rate = 0.25m;`), so the body reads the declared value and may overwrite it — C#'s order. Object initializers are the ones that run after. - **A required parameter must be supplied**: if the constructor has a non-optional parameter, `new T { … }` (no arguments) is a compile error — pass the argument. - Durable: a suspension **inside** a constructor body survives serialize/restore, and `new T(args)` still evaluates to the same constructed instance on resume. ## Examples {#examples} ```osy title="a class with a constructor" test app=constructors class Order { public int Qty; public decimal Total; public string Note; // The ctor assigns every required member, so `new Order(5, 2m)` compiles without also naming them in an // initializer — the compiler infers that the constructor satisfies them (no annotation needed). public Order(int qty, decimal price) { Qty = qty; Total = qty * price; Note = "new order"; } } // The constructor sets the fields from its arguments. decimal OrderTotal() { var o = new Order(5, 2m); return o.Total; // 10 (5 * 2, set in the body) } // An initializer is applied AFTER the body — so it wins. string OrderNote() { var o = new Order(5, 2m) { Note = "rush" }; return o.Note; // "rush" (the body set "new order"; the initializer overrode it) } ``` ```osy title="default parameters and the implicit default constructor" test app=constructors class Box { public int Size; public Box(int size = 3) { Size = size; } } int DefaultSize() { var b = new Box(); return b.Size; } // 3 (the constructor's default) int GivenSize() { var b = new Box(7); return b.Size; } // 7 // A class with no declared constructor keeps the plain build. class Point { public int X; public int Y; } int Origin() { var p = new Point { X = 0, Y = 0 }; return p.X + p.Y; } // 0 ``` ### Several constructors, and chaining between them {#overloads} Declare as many as differ in their parameter types. `: this(…)` runs another of them first, which is how shared setup stays in one place: ```osy title="three ways to make a Panel" test app=constructors class Panel { public decimal Width; public decimal Height; public Panel(decimal width, decimal height) { // the one that actually assigns Width = width; Height = height; } public Panel(decimal width) : this(width, 20m) { } // chains to it public Panel() : this(10m) { } // …and so does this, one hop further } ``` Each `new` picks by its arguments, and a chain runs all the way down before the chaining body: ```osy title="each new selects, and the chain completes" run app=constructors [Test] void Constructors_Select_And_Chain() { Assert.Equal(3m, new Panel(3m, 4m).Width); Assert.Equal(20m, new Panel(3m).Height); // the default the one-arg constructor passed on Assert.Equal(10m, new Panel().Width); // two hops: () → (decimal) → (decimal, decimal) } ``` ## See also {#see-also} - [class methods](https://osysharp.com/reference/class/methods/) — instance methods on a class (the same member-body mechanism the constructor reuses) - [Typed locals](https://osysharp.com/reference/function/typed-locals/) — declaring the local that holds a constructed instance --- # App configuration > The cross-cutting settings an app declares in one place — the app config object. Two kinds live here: the external providers and credentials your app depends on (secrets, OAuth clients, an embedding provider) and the app-wide policies (data classifications, audit-trail access, an MCP tool surface). Each is one typed declaration. ## Summary {#summary} Some things belong to the **whole app**, not to any one entity or function: the API keys it needs, the OAuth providers it signs users in with, the model it embeds text with, the sensitivity policy over its data. Those are declared once, as typed properties on the app config object, so there is a single place to look and the compiler checks each one. They fall into two groups: **what the app depends on** (secrets, OAuth clients, an embedding provider) and **policies over the app** (classifications, audit access, an MCP surface). ## Description {#description} ### What the app depends on {#dependencies} - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — `app.Secrets` declares the named secrets the app uses (API keys, tokens, client secrets). Each is `new Secret("Name")`; a value is never inlined in source. Mark one `{ UserScoped = true }` for a per-user secret. - [OAuth clients (app.OAuthClients)](https://osysharp.com/reference/config/oauth-clients/) — `app.OAuthClients` declares the third-party OAuth providers, both for signing users in and for calling an external API on a user's behalf. - [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) — `app.Embedding` names the embedding model that turns text into vectors, which is what powers semantic search over `[Searchable]` fields. - [per-environment config (app.Config)](https://osysharp.com/reference/config/app-config/) — `app.Config` declares the app's per-environment settings (`new Setting("Name")`), read anywhere as `Config.Name`; each environment supplies its values from a checked-in `.env.` file. Non-secret configuration — the counterpart to `app.Secrets`. ### Policies over the app {#policies} - [data classifications (app.Classifications)](https://osysharp.com/reference/config/classifications/) — `app.Classifications` maps a data-sensitivity level (a `DataClass` — PII, Financial, Secret, …) to the `[Role]` members allowed to read fields marked at that level. You declare the mapping once; fields opt in with a classification attribute. - [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) — `app.Audit` declares who may read the app's audit trail. The platform records entity changes automatically; this gates the reading of that record. - [workflow run retention (app.Workflow)](https://osysharp.com/reference/config/workflow/) — `app.Workflow` declares how long FINISHED workflow runs are kept. Undeclared, a completed run is kept for ever with everything it owns; a window reaps it, and a run still in progress is never reaped whatever its age. It is also a ceiling on how long [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) can keep the workflow transition trail. - [MCP tool server (app.McpServer)](https://osysharp.com/reference/config/mcp-server/) — `app.McpServer` exposes the app to an MCP client (an AI agent) as a set of tools, grouped into catalogs, each with its own visibility. ### UI surfaces the app owns {#ui} - [UI surfaces (app.Ui)](https://osysharp.com/reference/config/ui/) — `app.Ui` nominates the app's own components for the *system surfaces* the platform would otherwise draw a bare fallback for: `ConnectionSurface` (the server dropped — see [Connection](https://osysharp.com/reference/ui/connection/)), `NotFoundSurface` (404), `ForbiddenSurface` (403), and `ErrorSurface` (an unexpected load failure). ### One object, checked at compile time {#compile-time} Because each of these is a typed declaration rather than a config file parsed at boot, a missing provider, a misspelled role, or a secret that no code reads is caught when the app compiles — not in production. The [`use`](https://osysharp.com/reference/types/use/) declaration is the companion in the manifest: `use` brings a capability's tables and types into the app; the config object here tunes how the app uses them. ## See also {#see-also} - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) · [OAuth clients (app.OAuthClients)](https://osysharp.com/reference/config/oauth-clients/) · [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) — the app's external dependencies - [data classifications (app.Classifications)](https://osysharp.com/reference/config/classifications/) · [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) · [MCP tool server (app.McpServer)](https://osysharp.com/reference/config/mcp-server/) — the app-wide policies - [use](https://osysharp.com/reference/types/use/) — declaring a capability the app depends on --- # MCP tool server (app.McpServer) > `app.McpServer` exposes your app to an MCP client (an AI agent) as a set of tools. Tools are grouped into named `Catalogs`, each gated by a `VisibleTo` policy (who may see it). A tool is one of: `new Tool(Function)` (call one of your functions), `new CrudTool() { Operations = [...] }` (create/read/update/delete an entity), or `new Tool(Knowledge.Search)` (semantic search). A singleton. ## Summary {#summary} `app.McpServer` exposes your application to an MCP (Model Context Protocol) client — typically an AI agent — as a set of **tools** the agent may call. As with the REST surface, you **expose what you already have** rather than write a tool handler: a tool is one of your functions, an entity's CRUD operations, or a semantic search over your knowledge. Tools are grouped into named **catalogs**, and each catalog is gated by a `VisibleTo` policy that decides which principals may see and call it. `app.McpServer` is a **singleton** — an app has at most one MCP server. ```osy syntax app.McpServer = new McpServer { Catalogs = [ new ToolCatalog("admin-tools") { Description = "Admin-only tools", VisibleTo = IsAdmin, Tools = [ new Tool(OrderTotal) ], }, ], }; ``` ## Signature {#signature} ```osy syntax app.McpServer = new McpServer { Catalogs = [ // one entry per named group of tools new ToolCatalog("Name") { // the catalog's name, shown to the client Description = "…", // optional; describes the catalog to the agent VisibleTo = IsAdmin, // a declared `policy` — who may see this catalog Tools = [ // the tools this catalog exposes new Tool(OrderTotal), // call a function new CrudTool() { Operations = [CrudOp.Read] }, // CRUD over an entity new Tool(Knowledge.Search), // semantic search ], }, ], }; ``` `app.McpServer` is a singleton; its `Catalogs` is a list — an app may group its tools into several independently-gated catalogs. ## Description {#description} A `ToolCatalog` has: - **`"Name"`** — the catalog's name, passed to the constructor, shown to the MCP client. - **`Description`** *(optional)* — prose describing the catalog to the agent. - **`VisibleTo`** — the name of a declared `policy`. The catalog (and every tool in it) is only visible and callable to principals for whom the policy holds. `VisibleTo` must name a **declared policy** — an undeclared name is a compile error that lists your policies. The policy is defined over your `[Principal]` and its `[Role]`, e.g. `policy IsAdmin => user.Role == AppRole.Admin;`. - **`Tools`** — a list of tools. A tool is one of three kinds: - **`new Tool(Function)`** — exposes one of your functions as a callable tool. The function must be declared — an unknown name is a compile error that lists your functions. - **`new CrudTool() { Operations = [CrudOp.…] }`** — exposes create/read/update/delete over one entity; `Operations` chooses which of `Create` / `Read` / `Update` / `Delete` are available. The entity must be defined in your app. - **`new Tool(Knowledge.Search)`** — exposes semantic (vector) search over your app's searchable knowledge. A catalog is either a group of **CRUD/function tools** *or* a **polymorphic** tool group — a catalog mixes tool kinds freely, but each `Tools` entry is exactly one tool. You write no tool schema, no argument parsing, and no dispatch: the signature of the function and the shape of the entity are the contract. ## Examples {#examples} A complete app that exposes one function and one entity's full CRUD as an admin-only catalog. Note the catalog needs a declared `[Principal]`, its `[Role]` enum, and the `policy` that `VisibleTo` references: ```osy title="basic" test app=config-mcp-example entity Order { [Required, MaxLength(200)] string CustomerRef; decimal Total; } [Role] enum AppRole { Staff, Admin } [Principal] entity User { [MaxLength(200)] string Email; AppRole Role; } policy IsAdmin => user.Role == AppRole.Admin; decimal OrderTotal(decimal subtotal, decimal tax) { return subtotal + tax; } app.McpServer = new McpServer { Catalogs = [ new ToolCatalog("admin-tools") { Description = "Admin-only tools", VisibleTo = IsAdmin, Tools = [ new Tool(OrderTotal), new CrudTool() { Operations = [CrudOp.Create, CrudOp.Read, CrudOp.Update, CrudOp.Delete] }, ], }, ], }; ``` ## See also {#see-also} - [principal predicates (IsAuthenticated / IsAnonymous) and open reads](https://osysharp.com/reference/security/principal-predicates/) — the `[Principal]`, `[Role]`, and `policy` that `VisibleTo` gates a catalog with - [publishing a REST API (app.Apis)](https://osysharp.com/reference/api/rest/) — `app.Apis`, the HTTP surface that exposes the same functions and entities to non-agent callers - [using Memory (semantic search)](https://osysharp.com/reference/memory/search/) — the searchable knowledge that `new Tool(Knowledge.Search)` exposes --- # OAuth clients (app.OAuthClients) > `app.OAuthClients` declares the third-party OAuth providers your app uses — for signing users in (Login) and for connecting to an external API on a user's behalf (Connection). Each is `new OAuthClient("Name")` naming a Provider (Google/Github/Microsoft/Oidc), the Capabilities, a ClientId, and a ClientSecret (a `Secret.X` handle). Referenced elsewhere by its `OAuthClient.Name` handle. ## Summary {#summary} `app.OAuthClients` declares the third-party OAuth providers your application talks to. There are two reasons to declare one: to let users **sign in** with an external identity (Login), and to **connect** to an external API and act on a user's behalf (Connection). Each client is a `new OAuthClient("Name")` that names a `Provider`, the `Capabilities` you need, a `ClientId`, and a `ClientSecret` (a `Secret.X` handle). The client's `Name` is how the rest of your app refers back to it as `OAuthClient.Name`. ```osy syntax app.OAuthClients = [ new OAuthClient("Google") { Provider = OAuthProvider.Google, Capabilities = [OAuthCapability.Login], ClientId = "your-client-id", ClientSecret = Secret.GoogleOAuth, }, ]; ``` ## Signature {#signature} ```osy app.Secrets = [ new Secret("GoogleOAuth") ]; // the handle the client below reads app.OAuthClients = [ new OAuthClient("Name") { // one entry per provider client Provider = OAuthProvider.Google, // Google | Github | Microsoft | Oidc Capabilities = [OAuthCapability.Login, OAuthCapability.Connection], ClientId = "your-client-id", // the provider-issued client id ClientSecret = Secret.GoogleOAuth, // a Secret.X handle, never a literal }, ]; ``` `app.OAuthClients` is a list — an app may declare several clients, one per provider (or several against the same provider for different capabilities). ## Description {#description} An `OAuthClient` has: - **`Provider`** — an `OAuthProvider` enum member naming the identity provider: `Google`, `Github`, `Microsoft`, or `Oidc` (a generic OpenID Connect provider). - **`Capabilities`** — a list of `OAuthCapability`. `Login` lets users sign into your app with this provider; `Connection` lets your app connect to the provider's API and act on a signed-in user's behalf. A client may declare both. - **`ClientId`** — a string: the client identifier the provider issued when you registered your app with it. - **`ClientSecret`** — a `Secret.X` handle referring to a secret declared in [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/). You never write the secret value inline; you reference the named secret. The client's **`Name`** (the argument to `new OAuthClient("…")`) is its handle. That name is how the rest of your app refers back to the client as `OAuthClient.Name` — for example an `OAuthAuth` method that signs users in via this provider references the client by its `OAuthClient.Name` handle. ### The capability: `use Osysharp.Security.Oauth;` {#capability} Per-user OAuth links are a **capability**, `Osysharp.Security.Oauth`. Declaring an `OAuthClient` sets up the *provider*; the capability adds the per-**user** side: a `UserOAuthLink` entity that ties one of your app's users to the identity (and, for a `Connection` client, the stored tokens) they hold with a provider. The platform writes these links when a user signs in or connects; the `use`/`using` gates whether your own code may name and query them. - **`use Osysharp.Security.Oauth;`** in the `app { }` manifest declares the dependency. - **`using Osysharp.Security.Oauth;`** at the top of a source file imports the `UserOAuthLink` name so a function or query in that file may reference a user's linked provider identities. See [use](https://osysharp.com/reference/types/use/) for how `use` (the dependency) and `using` (the file-level import) differ. ## Examples {#examples} Declare the secret, then declare a Google client that lets users sign in: ```osy title="basic" test app=config-oauth-example app.Secrets = [ new Secret("GoogleOAuth") ]; app.OAuthClients = [ new OAuthClient("Google") { Provider = OAuthProvider.Google, Capabilities = [OAuthCapability.Login], ClientId = "your-client-id", ClientSecret = Secret.GoogleOAuth, }, ]; ``` ## See also {#see-also} - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — `app.Secrets`, where the `Secret.X` used by `ClientSecret` is declared - [[AuthMethod] — a function an unauthenticated visitor may call](https://osysharp.com/reference/security/auth-method/) — declaring an auth method that signs users in via an `OAuthClient` - [auth bootstrap (login, before anyone is signed in)](https://osysharp.com/reference/security/auth-bootstrap/) — granting the first user their role after an OAuth sign-in - [use](https://osysharp.com/reference/types/use/) — `use Osysharp.Security.Oauth;` (the dependency) and `using Osysharp.Security.Oauth;` (the import) --- # UI surfaces (app.Ui) > `app.Ui` nominates the app's own components for the "system surfaces" the platform would otherwise render a bare fallback for — the connection-loss overlay, the not-found (404) page, the forbidden (403) page, and the error page — and tunes the automatic busy indicator. A singleton; the `Ui` block groups these so more can be added without a new setting each time. ## Summary {#summary} `app.Ui` is where you hand the platform your **own** components for the *system surfaces* it would otherwise draw a bare fallback for — the "something happened, here's the app's branded page" moments. It is a **singleton** — one UI configuration per app — and it groups these overrides under one `Ui` block, so an app opts into each surface it wants to own and inherits the platform default for the rest. ```osy syntax app.Ui = new AppUi { ConnectionSurface = OfflineOverlay, // shown when the server drops mid-session NotFoundSurface = NotFoundPage, // shown (HTTP 404) when no route matches the address ForbiddenSurface = ForbiddenPage, // shown when a signed-in user is refused a page (403) ErrorSurface = ErrorPage, // shown when a page fails to load unexpectedly }; ``` ## Signature {#signature} ```osy app.Ui = new AppUi { ConnectionSurface = OfflineOverlay, // the connection-loss overlay NotFoundSurface = NotFoundPage, // the not-found (404) page ForbiddenSurface = ForbiddenPage, // the forbidden (403) page ErrorSurface = ErrorPage, // the error page }; ``` `app.Ui` is a single value, not a list. Each member names a component **by name** — the same name you gave it in its `component X { … }` declaration. ## Description {#description} An `AppUi` has these members (each optional — omit one, or omit `app.Ui` entirely, to keep the platform default): - **`ConnectionSurface`** — the component the platform mounts, as a fixed overlay over the current page, when the browser loses its link to the server. It reads the [Connection](https://osysharp.com/reference/ui/connection/) ambient (`Connection.State`, `Connection.Attempts`) and calls `Connection.Retry()` / `Connection.Reload()`. Because it has to render **with the server gone**, it must be self-contained — built from the [component](https://osysharp.com/reference/ui/component/) built-in elements, with no child components to fetch and no data to load. See [Connection](https://osysharp.com/reference/ui/connection/) for the full surface and its constraints. - **`NotFoundSurface`** — the page the platform serves, **with HTTP status 404**, when a visitor hits an address the app doesn't route. The server sends your app's shell with this component as the page (so the 404 keeps the correct status for crawlers and monitoring, but the *body* is your branded page instead of plain text) and the client renders it. Unlike the connection surface, a 404 means the server **answered**, so this page may use anything the app has. Mark it `[AllowAnonymous]` so a bad URL renders it for anyone rather than bouncing a signed-out visitor to login. - **`ForbiddenSurface`** — the page shown when a **signed-in** user is refused a page they aren't permitted to see (a 403). The platform mounts it in place of the built-in access-denied surface. - **`ErrorSurface`** — the page shown when a page fails to load for an **unexpected** reason, in place of the built-in "couldn't load" surface. Three more members tune the **busy indicator** — the automatic spinner the platform shows while an action is in flight (see [Pending](https://osysharp.com/reference/ui/pending/) for the full surface, including the `Pending` ambient): - **`PendingIndicator`** — your own component for the global busy affordance, in place of the built-in top progress bar. - **`PendingDelayMs`** — how long an action must run before the indicator appears (so an instant action never flashes one); `0` uses the platform default. - **`PendingMinShowMs`** — once shown, the minimum time the indicator stays up, so it can't blink off; `0` uses the default. The forbidden and error surfaces render at *boot-failure* time — a refusal or a failure that can happen **before the app has a working session, or while the server is unreliable**. So the platform **inlines their trees into the page** up front, and the client renders them with no further request. That is what makes them work when nothing else does — and it puts the same constraint on them as the connection surface: they must be **self-contained**, built from the [component](https://osysharp.com/reference/ui/component/) built-in elements (with `[Composable]` children bundled), carrying no data. Offer a way out with plain `Link`s (sign in as a different account, go home). Mark each `[AllowAnonymous]`. Each nominated component must exist, and none is a routed page — the platform serves or mounts each by name for its occasion, so none needs a `[Page("…")]`. `app.Ui` is a **singleton**: an app declares it once. Removing a member reverts that surface to the platform default. > Sign-in is deliberately **not** part of this block — it is a real *flow*, declared via > `app.AuthBootstrap { LoginPage = … }`, not a passive surface. ## Examples {#examples} Declare the surfaces, then nominate them: ```osy test app=ui-connection-and-notfound-surfaces [AllowAnonymous] component OfflineOverlay() { action Retry() { Connection.Retry(); } render { if (Connection.State == ConnState.Lost) { Row(align: Align.Center, justify: Justify.Center, position: Position.Fixed, inset: 0, bg: "#1a1a1a") { Text("Can't reach the server"); } } } } [AllowAnonymous] component NotFoundPage() { render { Row(align: Align.Center, justify: Justify.Center, minH: "100vh", bg: Colors.Surface) { Stack(gap: 3, align: Align.Center) { Text("Page not found"); Link(href: "/") { Text("Go home"); } } } } } app.Ui = new AppUi { ConnectionSurface = OfflineOverlay, NotFoundSurface = NotFoundPage, }; ``` ## See also {#see-also} - [Connection](https://osysharp.com/reference/ui/connection/) — the `Connection` ambient the connection surface reads, and its offline-render constraint. - [Pending](https://osysharp.com/reference/ui/pending/) — the automatic busy indicator the `Pending*` members tune, and the `Pending` ambient. - [component](https://osysharp.com/reference/ui/component/) — components, `render` blocks, and the built-in elements a surface is built from. --- # audit read access (app.Audit) > `app.Audit` configures the app's audit trails — WHO may read each one, and whether it is recorded at all. The platform keeps six trails on by default (entity changes, classified reads, workflow transitions, sign-ins, LLM calls, schedule occurrences); each read-surface (e.g. `EntityAuditRecord`) maps to an `AuditSurface` whose `Read = user => ` compiles to a deny-by-default read policy, and whose `Enabled = false` turns that trail off (audit is the developer's choice). ## Summary {#summary} `app.Audit` configures your app's **audit trails** — the records the platform keeps of what happened. You never write to a trail; `app.Audit` does two things: it gates **read** access (who may see a trail) and controls **capture** (whether a trail is recorded at all). Each read-surface — such as `EntityAuditRecord`, the per-entity change record — maps to a `new AuditSurface { … }` carrying an optional `Read = user => ` (a boolean over the `[Principal]` bound as `user`) and an optional `Enabled = `. Absent an `app.Audit` entry a surface is **on** (audit is on by default) and **deny-by-default for reads** (no one may read it until a `Read` predicate opens it). ```osy syntax app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Read = user => user.IsAuditor }, WorkflowAuditRecord = new AuditSurface { Enabled = false }, // turn a trail off }; ``` ## Signature {#signature} ```osy app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { // one entry per surface Read = user => user.IsAuditor, // (optional) who may read the trail — predicate over the [Principal] Enabled = true, // (optional) whether the trail is recorded — default true Retention = TimeSpan.FromDays(365), // (optional) how long rows are kept — default forever }, }; ``` `app.Audit` is a single `AuditConfig`. Each named surface (e.g. `EntityAuditRecord`) is an `AuditSurface` whose `Read` decides who may read that trail, `Enabled` decides whether it is captured, and `Retention` decides how long its rows are kept. All three members are optional; a surface with none is the default (on, closed to reads, kept forever). ## Description {#description} The audit trails are **not something you build** — the platform records them on its own. There are six, each a named read-surface: **`EntityAuditRecord`** (entity create/update/delete), **`AccessAuditRecord`** (reads of classified data), **`WorkflowAuditRecord`** (workflow transitions), **`AuthAuditRecord`** (sign-in events), **`LlmCallRecord`** (LLM calls — model, tokens, cost, and prompt/response), and **`ScheduleOccurrenceRecord`** (what a schedule did, or did not do, each time it came due). `app.Audit` configures them: - **`AuditConfig`** — the top-level value assigned to `app.Audit`. It holds one entry per surface you want to configure, plus the app-wide `Redact` policy. - **`AuditSurface`** — a surface's config, carrying two optional members: - **`Read = user => `** — who may read the trail. The predicate **binds the `[Principal]` as `user`** and **must be a boolean** over its fields (e.g. `user.IsAuditor`); a field it reads must exist on the `[Principal]`, or it is a compile error naming what the principal does define. It lowers to a **deny-by-default read policy plus an `allow read when ` rule**, enforced by the **same security runtime as every other entity** — no separate audit-permission path. A surface you never give a `Read` stays closed; one you do opens only to accepting principals. - **`Enabled = `** — whether the trail is captured at all. See [below](#enabled). - **`Retention = `** — how long rows are kept before the platform purges them. See [below](#retention). ### Turning a trail off: `Enabled` {#enabled} Every trail is **on by default**. `Enabled = false` on a surface turns that one off — the platform stops recording it: ```osy syntax app.Audit = new AuditConfig { WorkflowAuditRecord = new AuditSurface { Enabled = false }, // don't record workflow transitions AuthAuditRecord = new AuditSurface { Enabled = false }, // don't record sign-ins }; ``` - **Per-surface.** Each surface is switched independently; omit a surface (or set `Enabled = true`) to keep it on. Disabling `EntityAuditRecord` turns off the **whole** entity-change trail; for finer control, exclude a single entity with the `[Audit(None)]` attribute on its declaration. - **`Read` and `Enabled` are independent.** `Read` governs who may see an existing trail; `Enabled` governs whether the trail is written. They can be combined (`new AuditSurface { Read = user => user.IsAuditor, Enabled = false }`) or used alone. - **Auditing is the developer's choice** — including the sign-in trail. Turning `AuthAuditRecord` off is a declared decision not to capture sign-ins; it does not weaken the guarantee that, **while on**, the trail is complete and tamper-proof (host-written, read-only to your app). ### Redaction: what never appears in the trail {#redaction} The audit trail records **entity changes** — for each changed property, its old and new value. Some values must never be captured: a credential (`PasswordHash`, `ResetToken`) or a `[Classification]`-restricted field would otherwise land, **unmasked**, in a durable, exportable log. `app.Audit.Redact` declares — **explicitly** — what to hold back: - **`Redact = new AuditRedaction { … }`** — the app-wide redaction policy. Optional; declare it once. - **`Properties = [Entity.Prop, …]`** — these exact properties are redacted wherever an audit record would capture their value. - **`Classifications = [Enum.Member, …]`** — any property carrying one of these `[Classification]` levels is redacted. This names the **same** classification levels the app declares for read-masking, so audit-redaction and read-masking cannot drift. A redacted property **still appears** in the change record — the "it changed" signal is preserved — but its old and new values are replaced with the marker `‹redacted›`, never the raw value. Redaction is **declared, never inferred**: a property is redacted only if named here (directly, or via its classification). An app that declares no `Redact` captures values verbatim. The **same one `Redact` policy also governs the LLM-call trail**. A classified value your app is allowed to read may legitimately go into a prompt sent to the model — but if that value's property is covered by `Redact`, it must not be persisted in the `LlmCallRecord` body. There is nothing extra to declare: the property's `[Classification]` (or its name in `Redact`) is the whole instruction. The model still receives the value; the retained log does not. Precise value-level redaction lands as the platform gains typed visibility into what an agent feeds a model; until then a call known to carry such a value is logged **metrics-only** (tokens/cost/timing kept, prompt/response body dropped) — never a partial leak. ### How long rows are kept: `Retention` {#retention} By default a trail's rows are kept **forever**. `Retention = ` sets a window; the platform periodically purges that surface's rows older than the window. Use the standard C# `TimeSpan` factories: ```osy syntax app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Retention = TimeSpan.FromDays(365) }, // keep a year of changes AccessAuditRecord = new AuditSurface { Retention = TimeSpan.FromDays(90) }, // keep 90 days of access logs }; ``` - **Per-surface, constant.** Each surface has its own window; a surface with no `Retention` is kept forever. The window is a compile-time constant — `TimeSpan.FromDays(…)` / `FromHours(…)` / `FromMinutes(…)` / `FromSeconds(…)` over a literal (not a per-row expression). - **Enforced by a platform sweep.** A platform-owned background job runs periodically (per app) and deletes each surface's expired rows — you declare the window; the platform does the deleting. It is best-effort and eventually consistent: rows are removed on the next sweep after they age out, not at the exact instant. #### Two horizons for the LLM trail: `ContentRetention` {#llm-retention} The `LlmCallRecord` trail is special: each row holds a fat **body** (the prompt, response, and tool definitions) *and* billing-grade **metrics** (tokens, cost, provider, model). Those want opposite lifetimes — the body is sensitive and should expire quickly, the cost record is a financial fact you keep for reporting. So the LLM surface takes **two** windows: ```osy syntax app.Audit = new AuditConfig { LlmCallRecord = new AuditSurface { ContentRetention = TimeSpan.FromDays(30), // the BODY (prompt/response) is cleared after 30 days Retention = TimeSpan.FromDays(365), // the whole record (incl. cost) is deleted after a year } }; ``` - **`ContentRetention`** — how long the prompt/response **body** is kept. Past it, the sweep **nulls the body columns** but keeps the row and all its metrics/cost. This member is **LLM-only** (no other surface has a body-vs-metrics split; declaring it elsewhere is a compile error). - **`Retention`** — how long the **record** is kept, exactly as for the other surfaces; past it the whole row is deleted. For `LlmCallRecord` this is the metrics/cost horizon, and should be ≥ `ContentRetention`. - Omit `ContentRetention` and the body lives as long as the record; omit `Retention` and the metrics are kept forever (bodies still expire on `ContentRetention` if set). ### System-access (sign-in) trail: `AuthAuditRecord` {#auth-trail} Beyond entity changes, the platform records **system-access events** — who logged in, who FAILED to, and who logged out — on the `AuthAuditRecord` surface. Every sign-in path routes its outcome through one funnel that writes the trail, so it is complete across providers by construction: the platform-managed password and OAuth flows, and an app's OWN sign-in (an `[AuthMethod]` function that calls `Security.IssueJwt`) — a successful `Security.IssueJwt` records a `LoginSucceeded` for you. Each row carries the `Event` (`LoginSucceeded` / `LoginFailed` / `SignupSucceeded` / `Logout`), the `AttemptedLogin` (the username tried — the brute-force / account-enumeration signal, recorded even for a failed unknown-user attempt), the `AuthMethod`, a `FailureReason` on a failure, and the client info. Like every trail it is **host-written and read-only** to your app, gated by `app.Audit.AuthAuditRecord.Read`, and — like every trail — subject to `Enabled` (see [above](#enabled)): an app may decline to record sign-ins with `AuthAuditRecord = new AuditSurface { Enabled = false }`. ### LLM-call trail: `LlmCallRecord` {#llm-trail} Every call your app makes to a language model is recorded on the `LlmCallRecord` surface — the model and provider, the token counts (input / output / cache), the computed **cost**, the timing, and (when logging is on) the prompt and response. It is the per-call ledger behind "what did this app spend on which model." Like every trail it is **host-written and read-only** to your app, gated by `app.Audit.LlmCallRecord.Read`, and switched by `Enabled`: ```osy syntax app.Audit = new AuditConfig { LlmCallRecord = new AuditSurface { Read = user => user.IsAuditor, Enabled = true }, }; ``` - **`Enabled = false` turns the whole per-call trail off** — no call rows are written. It does **not** affect the LLM budget: your daily token/cost limits are still enforced and rolled up (spend control is independent of the audit log). - **The record is queryable** with `using Osysharp.Llm.Observability;` (its own capability), the same way the other trails open with `using Osysharp.Observability;` — see [below](#capability). ### Schedule-occurrence log: `ScheduleOccurrenceRecord` {#occurrence-trail} A [Schedule (recurring work)](https://osysharp.com/reference/scheduling/schedule/) produces work on a cadence whether or not anyone is watching, so the question people ask it is usually about the times it produced **nothing**. The `ScheduleOccurrenceRecord` surface answers that: one row for every occurrence the platform considered, carrying when it was `DueAt`, when the platform looked (`At`), the `Outcome` (`Produced` / `Skipped` / `Retired` / `UnknownTarget`), the row it produced, and `CoalescedCount` — how many further occurrences a catch-up absorbed. Every consideration is recorded, **the ordinary ones included**, and that is what gives an absent row a meaning: no record for last night means the platform never looked, which is a different fault from a night that was skipped. A trail holding only the exceptions leaves those two indistinguishable. Unlike the other five, this trail's producer is a **cadence rather than a person** — a minutely schedule writes some half a million rows a year — so it is the one most worth a `Retention` window: ```osy syntax app.Audit = new AuditConfig { ScheduleOccurrenceRecord = new AuditSurface { Read = user => user.IsOnCall, Retention = TimeSpan.FromDays(90), } }; ``` ### The capability: `use Osysharp.Observability;` {#capability} The audit trail is a **capability**, `Osysharp.Observability`. Its schema is always present — the platform records `EntityAuditRecord` (entity create/update/delete), `AccessAuditRecord` (reads of classified data), and `AuthAuditRecord` (sign-in events) whether or not your app opts in. The `use`/`using` for `Osysharp.Observability` gates one thing: whether your own code may **name** the audit records to query them. - **`use Osysharp.Observability;`** in the `app { }` manifest declares the dependency. - **`using Osysharp.Observability;`** at the top of a source file imports the audit read-surface names, so a function or query in that file may reference `EntityAuditRecord` / `AccessAuditRecord` / `AuthAuditRecord`. `ScheduleOccurrenceRecord` is the exception that needs no `using` at all — a schedule is core rather than a capability, so its occurrence log is in scope wherever you write a query. `app.Audit` (above) then decides **who** may read what you thus reference — the capability opens the names to your code; the `Read` predicates open the rows to a principal. See [use](https://osysharp.com/reference/types/use/) for how `use` and `using` differ. ## Examples {#examples} An app whose audit trail is readable only by staff flagged as auditors. The `[Principal]` declares the `IsAuditor` field the predicate reads: ```osy title="basic" test app=config-audit-example [Principal] entity Staff { [Required, MaxLength(200)] string Name; bool IsAuditor; } app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Read = user => user.IsAuditor } }; ``` Redaction alongside the read gate: the account's password hash (by its `Secret` classification) and its API key (named directly) are recorded as `‹redacted›`, never verbatim, while ordinary fields are captured as-is: ```osy title="redaction" test app=config-audit-redaction enum DataClass { Public, Secret } [Principal] entity Staff { [Required, MaxLength(200)] string Name; bool IsAuditor; } entity Account { [Required, MaxLength(200)] string Login; [MaxLength(200)] [Classification(DataClass.Secret)] string PasswordHash; string ApiKey; } app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Read = user => user.IsAuditor }, Redact = new AuditRedaction { Properties = [Account.ApiKey], // this exact property Classifications = [DataClass.Secret] // any property at the Secret level (Account.PasswordHash) } }; ``` Turning trails off is per-surface and independent of the read gate. Here workflow-transition auditing is disabled outright, while the entity-change trail stays on but readable only by auditors: ```osy title="enabled" test app=config-audit-enabled [Principal] entity Staff { [Required, MaxLength(200)] string Name; bool IsAuditor; } app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Read = user => user.IsAuditor }, WorkflowAuditRecord = new AuditSurface { Enabled = false } }; ``` Retention windows keep the trail bounded — a year of entity changes, ninety days of access logs, sign-ins forever: ```osy title="retention" test app=config-audit-retention [Principal] entity Staff { [Required, MaxLength(200)] string Name; bool IsAuditor; } app.Audit = new AuditConfig { EntityAuditRecord = new AuditSurface { Read = user => user.IsAuditor, Retention = TimeSpan.FromDays(365) }, AccessAuditRecord = new AuditSurface { Retention = TimeSpan.FromDays(90) } // AuthAuditRecord has no Retention → sign-ins are kept forever }; ``` ## See also {#see-also} - [principal predicates (IsAuthenticated / IsAnonymous) and open reads](https://osysharp.com/reference/security/principal-predicates/) — the `user => …` predicate form, and the `[Principal]` it binds - [security { }](https://osysharp.com/reference/security/entity-security/) — the deny-by-default read policy + `allow read when` rule this lowers to - [role grants (and the first admin)](https://osysharp.com/reference/security/role-grants/) — granting a principal the role a predicate can test - [use](https://osysharp.com/reference/types/use/) — `use Osysharp.Observability;` (the dependency) and `using Osysharp.Observability;` (the import) - [Schedule (recurring work)](https://osysharp.com/reference/scheduling/schedule/) — the recurring producer behind the `ScheduleOccurrenceRecord` trail --- # data classifications (app.Classifications) > Classifications map a data-sensitivity level (a `DataClass` — PII, Financial, Secret, …) to the `[Role]` members allowed to read fields marked at that level. Declared inside the bare `app = new() { … }` config object. A field marked `[Classification(DataClass.PII)]` is readable only by a principal holding one of the roles listed for PII. ## Summary {#summary} `app.Classifications` maps each **data-sensitivity level** to the set of `[Role]` members permitted to read fields marked at that level. A level is a `DataClass` value — `PII`, `Financial`, `Secret`, and so on — and each `Classification` pairs one level with a `Roles = [ … ]` list. A field annotated `[Classification(DataClass.PII)]` is then readable only by a principal holding one of the roles listed for PII; to everyone else the field is masked. The list is declared inside the bare `app = new() { … }` config object. ```osy syntax enum DataClass { PII, Financial } app = new() { Name = "Orders", Classifications = [ new Classification(DataClass.PII) { Roles = [Role.Staff, Role.Admin] }, new Classification(DataClass.Financial) { Roles = [Role.Admin] }, ], }; ``` ## Signature {#signature} ```osy [Role] enum Role { Staff, Admin } // the [Role] enum must be declared enum DataClass { PII, Financial } // …and the level vocabulary is an enum too app = new() { Name = "Orders", Classifications = [ // one entry per data-sensitivity level new Classification(DataClass.PII) { // the level this entry governs Roles = [Role.Staff, Role.Admin], // roles allowed to read fields at this level }, new Classification(DataClass.Financial) { Roles = [Role.Admin] }, ], }; ``` `Classifications` is a list — an app may map several independent `DataClass` levels, each to its own set of roles. ## Description {#description} Each `Classification` has: - **`DataClass.`** — the constructor argument names the sensitivity level this entry governs (`PII`, `Financial`, `Secret`, …). One entry per level. The level vocabulary is an **enum the app declares** — it need not be called `DataClass`, and naming a member no enum declares is a compile error, exactly as it is in the `[Classification]` attribute. - **`Roles`** — a list of `[Role]` enum members. A principal must hold **one of** these roles to read a field marked at this level. A principal holding none of them sees the field masked. A field opts into a level with the **`[Classification]`** attribute — `[Classification(DataClass.)]` on the member. The classification declared here is what that attribute resolves against: it decides which roles can read the field. Because `Roles` references `[Role]` members, the **`[Role]` enum must be declared** in the app — a role name that doesn't resolve is a compile error that names the roles you do define. The whole list lives inside the bare `app = new() { Name = "…", Classifications = [ … ] }` config object alongside the app's other configuration. ## Examples {#examples} An app that classifies `PII` fields as readable by staff or admins, and `Financial` fields as admin-only. The `[Role]` enum is declared because `Roles` references its members: ```osy title="basic" test app=config-classifications-example [Role] enum Role { Staff, Admin } enum DataClass { PII, Financial } app = new() { Name = "Orders", Classifications = [ new Classification(DataClass.PII) { Roles = [Role.Staff, Role.Admin] }, new Classification(DataClass.Financial) { Roles = [Role.Admin] }, ], }; ``` ## See also {#see-also} - [role grants (and the first admin)](https://osysharp.com/reference/security/role-grants/) — declaring the `[Role]` enum whose members appear in `Roles` - [security { }](https://osysharp.com/reference/security/entity-security/) — entity-level read/write gates that compose with field classifications - [principal predicates (IsAuthenticated / IsAnonymous) and open reads](https://osysharp.com/reference/security/principal-predicates/) — the principal whose roles are checked against a field's classification --- # declaring secrets (app.Secrets) > `app.Secrets` declares the named secrets your app uses — API keys, tokens, client secrets. Each is `new Secret("Name")`, optionally `{ UserScoped = true }` for a per-user secret rather than one app-wide value. Everything else references a secret by its `Secret.Name` handle — `app.DefaultModel`'s `ApiKey`, an OAuth client's `ClientSecret`. A secret's VALUE is never in source, only its name; the value lives in the secret store. ## Summary {#summary} `app.Secrets` declares the named secrets your application **consumes** — a provider's API key, an access token, an OAuth client secret. You declare a secret's **name** here; you never write its **value** in source. ⚠ **Not the API key of an API your app PUBLISHES.** That is a different direction and a different mechanism: a published `app.Apis` route gated `Auth = new ApiAuth { ApiKey = true }` is authenticated by a **per-user** key kept on the app's `[Principal]` row, and nothing in `ApiAuth` names a `Secret`. See [publishing a REST API (app.Apis)](https://osysharp.com/reference/api/rest/). Each secret is `new Secret("Name")`, and optionally `{ UserScoped = true }` to make it a per-user secret rather than a single app-wide value. Every other config slot that needs a secret refers to it by its `Secret.Name` handle rather than by an inline string. ```osy syntax app.Secrets = [ new Secret("OpenAI"), new Secret("PersonalToken") { UserScoped = true }, ]; ``` ## Signature {#signature} ```osy app.Secrets = [ // one entry per named secret new Secret("Anthropic"), // app-wide: one value for the whole app new Secret("CalendarToken") { UserScoped = true }, // per-user: each user supplies their own value ]; // referenced elsewhere by handle, never by literal value: app.DefaultModel = new LlmConfig { ApiKey = Secret.Anthropic }; ``` `app.Secrets` is a list — an app may declare as many named secrets as it needs. ## Description {#description} Each entry is a `new Secret("Name")`, where the name is a **string literal**. That name is the only thing that lives in source. The secret's actual value — the key, token, or password — is never written in your app; it lives in the secret store and is supplied separately. On your own machine you supply it with `osy secret set` ([Giving a secret its value](https://osysharp.com/reference/local/giving-a-secret-its-value/)); a deployed app's values are supplied by whoever operates its platform. - **`new Secret("Name")`** — declares an **app-wide** secret. There is one value, shared by the whole application, used for every request regardless of who makes it (for example, one server-side API key for a provider). - **`{ UserScoped = true }`** — makes the secret **per-user** instead. Every user of the app supplies their own value, and the secret resolves to the value belonging to the current user. Use this when the credential belongs to the person, not the app (for example, a user's personal access token). Once declared, a secret is referenced everywhere else by its **`Secret.Name` handle** — not by re-typing the name as a string and never by the value. `app.DefaultModel`'s `ApiKey`, an OAuth client's `ClientSecret`, and a REST API's key all take a `Secret.Name` handle. The handle is how the platform links a config slot to the stored value at runtime while keeping the value itself out of your source. ## Examples {#examples} Declare an app-wide secret and reference it from the default model's `ApiKey`: ```osy title="basic" test app=config-secrets-example app.Secrets = [ new Secret("OpenAI") ]; app.DefaultModel = new LlmConfig { Provider = LlmProvider.OpenAI, Model = "gpt-4o", ApiKey = Secret.OpenAI, }; ``` A per-user secret — each user supplies their own value: ```osy title="user-scoped" test app=config-secrets-userscoped app.Secrets = [ new Secret("PersonalToken") { UserScoped = true } ]; ``` ## See also {#see-also} - [reading a secret's value (Secret.Name)](https://osysharp.com/reference/function/secret-read/) — reading a declared secret's VALUE inside a function body - [Giving a secret its value](https://osysharp.com/reference/local/giving-a-secret-its-value/) — how a declared secret gets its value on your machine - [OAuth clients (app.OAuthClients)](https://osysharp.com/reference/config/oauth-clients/) — an OAuth client's `ClientSecret` is a `Secret.Name` handle - [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — `app.DefaultModel`, whose `ApiKey` references a declared secret - [publishing a REST API (app.Apis)](https://osysharp.com/reference/api/rest/) — `app.Apis`. ⚠ A REST API's key is NOT one of these: `ApiAuth` names no `Secret`, and a published API's key is a per-user credential kept on the `[Principal]` row --- # embedding provider (app.Embedding) > `app.Embedding` declares the embedding model the app uses to turn text into vectors for semantic search over `[Searchable]` fields (see `Memory.Search`). You name a `Provider`, a `Model` string, the `ApiKey` (a `Secret.X` handle), and the vector `Dimensions` — plus an optional `BaseUrl` to run the model at an endpoint you choose. A singleton. ## Summary {#summary} `app.Embedding` declares the embedding model your application uses to turn text into vectors, so that semantic search over `[Searchable]` fields (queried through `Memory.Search`) has something to embed against. You name a **provider**, a **model**, the **secret** that authenticates to that provider, and the **dimensions** of the vectors it returns. It is a **singleton** — one embedding configuration per app. ```osy syntax app.Embedding = new EmbeddingConfig { Provider = EmbeddingProvider.OpenAI, Model = "text-embedding-3-small", ApiKey = Secret.OpenAI, Dimensions = 1536, }; ``` ## Signature {#signature} ```osy app.Secrets = [ new Secret("OpenAI") ]; // the handle the config below reads app.Embedding = new EmbeddingConfig { Provider = EmbeddingProvider.OpenAI, // which embedding provider Model = "text-embedding-3-small", // the provider's embedding model id ApiKey = Secret.OpenAI, // a Secret.X handle from app.Secrets Dimensions = 1536, // the width of the produced vectors BaseUrl = "https://…/v1/embeddings", // optional — where to run it (default: the provider's own endpoint) }; ``` `app.Embedding` is a single value, not a list — an app configures exactly one embedding model. ## Description {#description} An `EmbeddingConfig` has five members, four of them required in practice: - **`Provider`** — an `EmbeddingProvider` enum member naming which service produces the vectors. The example uses `EmbeddingProvider.OpenAI`. - **`Model`** — the provider's embedding model id, as a string (for example `"text-embedding-3-small"`). This chooses which model the provider runs. - **`ApiKey`** — a `Secret.X` handle referencing a secret declared in `app.Secrets`. It authenticates calls to the provider; the value itself lives outside your source. - **`Dimensions`** — the width of each produced vector (for example `1536`). This must match the vector size the chosen model emits, so that stored `[Searchable]` vectors and query vectors are comparable. - **`BaseUrl`** — optional. The endpoint that actually computes the embeddings. Omit it and the provider's own endpoint is used; give it and the model runs wherever you say — a service you host, a regional deployment, an inference endpoint inside a particular jurisdiction. It is the whole URL, not a host to append a path to, because a compatible service may mount the protocol wherever it likes. `Provider` takes one of three values: | Provider | What it means | |---|---| | `EmbeddingProvider.OpenAI` | OpenAI's own embeddings endpoint. `BaseUrl` optional (a proxy in front of it). | | `EmbeddingProvider.Google` | Google's embeddings. | | `EmbeddingProvider.OpenAICompatible` | Any service speaking the OpenAI embeddings protocol. **`BaseUrl` required** — the provider means "that protocol, at an endpoint you name", so there is no sensible default. | > **The platform ships no embedding model of its own, on purpose.** A vector column is sized for the model that > fills it, and vectors from one model are never comparable with another's — so an app that embedded with a small > bundled model in development and a hosted one in production was never testing the feature it shipped. Declare one > embedder and use it everywhere: locally, in tests, in production. It costs nothing to keep it free and offline: > run an OpenAI-protocol embedding server on your own machine or in your own network and point > `EmbeddingProvider.OpenAICompatible` at it — the second example below is exactly that. **Why `BaseUrl` matters even when you are using OpenAI.** Where a model runs can be a requirement rather than a preference — data-residency obligations are usually written about *where the data goes*, and embedding is the operation that reads every indexed row. [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) takes a `BaseUrl` for the same reason — chat and embeddings answer the same placement question, and an app that must place one almost always has to place both. `app.Embedding` is a **singleton**: an application declares one embedding configuration, and every `[Searchable]` field and every `Memory.Search` query uses it. ## Examples {#examples} Declare the secret, then configure OpenAI embeddings against it: ```osy title="basic" test app=config-embedding-example app.Secrets = [ new Secret("OpenAI") ]; app.Embedding = new EmbeddingConfig { Provider = EmbeddingProvider.OpenAI, Model = "text-embedding-3-small", ApiKey = Secret.OpenAI, Dimensions = 1536, }; ``` Place the model at your own endpoint — the same declaration, with the provider and endpoint changed: ```osy title="an embedding model you host" test app=config-embedding-placed app.Secrets = [ new Secret("Embeddings") ]; app.Embedding = new EmbeddingConfig { Provider = EmbeddingProvider.OpenAICompatible, Model = "bge-m3", ApiKey = Secret.Embeddings, Dimensions = 1024, BaseUrl = "https://embeddings.internal.example/v1/embeddings", }; ``` ## See also {#see-also} - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — `app.Secrets`, where the `ApiKey` handle referenced by `Embedding` is declared - [[Searchable]](https://osysharp.com/reference/memory/searchable/) — marking a field `[Searchable]` so its text is embedded for search - [using Memory (semantic search)](https://osysharp.com/reference/memory/search/) — `Memory.Search`, the query that runs against the embedded vectors - [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — `app.DefaultModel`, the same placement question for the chat model --- # identifier patterns (app.Memory) > `app.Memory` tells search what an identifier looks like in YOUR data — an order number, a part code, an SKU. Search already spots identifier-shaped tokens in a query and matches them exactly, but it has to guess at the shape; declaring the patterns replaces the guess with an answer, and turns the guessing off. ## Summary {#summary} Some tokens carry meaning no amount of language understanding can recover: `ORD-004471`, `AB1234X`, `000346`. A search engine that only understands *meaning* cannot find them reliably, so the platform also matches such tokens EXACTLY, and weights that match heavily — but only when it is confident the query contains one. Left alone it decides by shape: a token with a digit and at least four characters. That works, and it is a guess about your data. `app.Memory` lets you state the shapes instead. ## Signature {#signature} ```osy syntax app.Memory = new MemoryConfig { Identifiers = [ @"ORD-\d{6}", @"[A-Z]{2}\d{4}[A-Z]" ] }; ``` ## Description {#description} Each entry is a regular expression. A query is scanned for them, and anything found is matched exactly against the corpus alongside the ordinary meaning-based search. **Declaring turns the built-in guessing OFF.** You have answered the question the guess was standing in for, and running both would put the guesses back on exactly the queries your patterns did not match — the ones you have implicitly said contain no identifier. That matters because the shape guess is not perfect on real language. Measured against a public benchmark, it fired on 6 of 470 questions and five of those were not identifiers at all — `15th`, `10th`, `5-day`, `pre-1920`. Those now abstain, but a corpus whose codes look like ordinary numbers is still better served by saying so. **Patterns are checked when you compile.** A pattern that is not a valid regular expression is a compile error naming it — not a search that fails later, in production, on the first query that happens to reach it. **They are also checked for SPEED.** Patterns run once per query against text a caller supplied, so a pattern that can take exponential time on an unlucky input is refused at compile time rather than becoming a way to stall your app. In practice this rules out backreferences and lookaround; ordinary character classes, quantifiers and anchors are all fine. Use `@"…"` for a pattern, as in every example here. Inside `@"…"` a backslash is just a backslash, which is what a regular expression is made of. **Removing the declaration puts you back to the built-in behaviour** — the stored patterns go with it. ## Examples {#examples} ```osy title="declare the shapes your data uses" test app=memory-identifiers using Osysharp.Memory; entity Order { [MaxLength(64)] string Reference; [Searchable(Memory)] string? Notes; } app.Memory = new MemoryConfig { Identifiers = [ @"ORD-\d{6}", @"[A-Z]{3}-\d{4}" ] }; ``` ```osy title="a query naming one is matched exactly, as well as by meaning" test app=memory-identifiers using Osysharp.Memory; List Chase(string question) { // "did we ever sort out the packaging fault on ORD-004471?" matches that order's notes on the token // itself — not merely on sounding like a packaging complaint. return Memory.Search(question, limit: 5); } ``` ## See also {#see-also} - [using Memory (semantic search)](https://osysharp.com/reference/memory/search/) — the search this configures - [How retrieval works](https://osysharp.com/reference/memory/how-retrieval-works/) — why an exact token match is treated differently from a meaning match - [per-environment config (app.Config)](https://osysharp.com/reference/config/app-config/) — the rest of the `app.` configuration surface --- # per-environment config (app.Config) > `app.Config` declares your app's per-environment settings — values that differ between development and production, like an invite base URL or a from-address. Each is `new Setting("Name")` with an optional `Default`; the real per-environment values come from checked-in `.env.development` / `.env.production` files. Read a setting anywhere with the `Config.Name` handle — in a function body and in a component — and it resolves to the value for the environment the app is running in. ## Summary {#summary} `app.Config` declares the **per-environment settings** your application uses — non-secret values that differ between development and production, such as an invite base URL (`http://localhost:8099` locally, `https://app.example.com` in production) or a from-address. It is the **non-secret twin of [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/)**: you declare a setting's **name** in source and supply its per-environment **values** out of band, but — unlike a secret — a setting's value is public and is **readable everywhere** through the `Config.Name` handle, in a function body and in a component alike. ```osy syntax app.Config = [ new Setting("InviteBaseUrl") { Default = "http://localhost:8099" }, new Setting("FromAddress") { Default = "noreply@localhost" }, ]; // read it anywhere by handle — it resolves to the running environment's value: string invite = Config.InviteBaseUrl + "/accept?token=" + token; ``` ## Signature {#signature} ```osy syntax app.Config = [ // one entry per named setting new Setting("Name") { Default = "…" }, // Default: the value used when no .env supplies one new Setting("Name"), // no Default: the value is REQUIRED from a .env file ]; Config.Name // the setting's value for the running environment (a string) ``` `app.Config` is a list — an app may declare as many named settings as it needs. ## Description {#description} A setting has a **name** (a string literal, the `Config.Name` read key) and an optional **`Default`**. The name and the `Default` are the only things that live in source. The actual per-environment values come from two checked-in files that sit next to your `app.osy`: - **`.env.development`** and **`.env.production`** — plain `KEY=VALUE` files (`#` comments and blank lines ignored). A key names a setting; its value is that setting's value for that environment. These `.env` files are **compile inputs**, not runtime reads: when you compile, both value sets are baked into the app, so one compiled app carries its development *and* its production values and needs no per-environment recompile. For each setting, the value in each environment is the `.env` override if present, otherwise the setting's `Default`. At runtime the app **selects** the set matching the environment it is running in — a local dev server resolves the development values, a production deployment resolves the production ones — so `Config.InviteBaseUrl` reads `http://localhost:8099` locally and `https://app.example.com` in production, from the same build. **Reading a setting.** `Config.Name` is a plain string value. Use it in a function body (building an email link, choosing a from-address) and in a component (a link, a label). Reading a setting that is not declared in `app.Config` is a compile error — a typo never silently reads as empty. **Required vs. defaulted.** A setting with a `Default` always has a value. A setting **without** a `Default` is *required*: if either `.env.development` or `.env.production` does not supply it, the compile fails — you cannot ship a build that is missing a value in an environment it targets. An `.env` key that matches no declared setting is likewise a compile error, so a stale or mistyped key is caught rather than silently ignored. **Not for secrets.** `app.Config` values are stored and served in the clear — they are meant to be public (a URL, an address), and a component can read them. An API key, token, or password belongs in [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/), which keeps its value out of source and never sends it to a browser. A config value that looks like a secret (a long random token, an `sk-…` key) is flagged with a warning nudging you toward `app.Secrets`. ## Examples {#examples} Declare two settings with development defaults, and read one in a function that builds an invite link: ```osy title="basic" test app=config-app-config-example app.Config = [ new Setting("InviteBaseUrl") { Default = "http://localhost:8099" }, new Setting("FromAddress") { Default = "noreply@localhost" }, ]; string InviteLink(string token) { return Config.InviteBaseUrl + "/accept?token=" + token; } ``` To give production a different value, add a checked-in `.env.production` next to your `app.osy`: ```text title=".env.production" InviteBaseUrl=https://app.example.com FromAddress=hello@example.com ``` Now `Config.InviteBaseUrl` reads `http://localhost:8099` when the app runs locally and `https://app.example.com` when it runs in production — from one compiled build, with no code change. ## See also {#see-also} - [declaring secrets (app.Secrets)](https://osysharp.com/reference/config/secrets/) — the SECRET twin: a value kept out of source and never served to the client - [embedding provider (app.Embedding)](https://osysharp.com/reference/config/embedding/) — another `app.X` config block (the embedding model) - [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — `app.DefaultModel`, the app's default LLM config --- # workflow run retention (app.Workflow) > `app.Workflow` declares how long the app keeps FINISHED workflow runs. Without it a completed run is kept for ever, along with everything it owns — its work items, its timers and its transition trail. With it, a run whose terminal state is older than the window is reaped, and its children go with it. A run still in progress is never reaped, whatever its age. ## Summary {#summary} `app.Workflow` declares how long the app keeps **finished** workflow runs. A run that reaches a terminal state still occupies a row, and so does everything it owns — its work items, its timers, its stored step results and its transition trail. Nothing removes them unless you say so, so an app accumulates every run it has ever executed. Declaring a `Retention` window changes that: a run whose completion is older than the window is reaped on a background sweep, and its children are reaped with it. Two things are guaranteed and neither is configurable — **a run that has not finished is never reaped, however old it is**, and **with no window declared nothing is ever reaped**. Deleting an app's data on a default nobody chose is not a decision the platform makes for you. ```osy syntax app.Workflow = new WorkflowConfig { Retention = TimeSpan.FromDays(90) }; ``` ## Signature {#signature} ```osy app.Workflow = new WorkflowConfig { Retention = TimeSpan.FromDays(90), // (optional) how long a FINISHED run is kept after it completes }; ``` `Retention` takes the same constant `TimeSpan.From…` factory that [`app.Audit`](https://osysharp.com/reference/config/audit/) retention takes — `FromDays`, `FromHours`, `FromMinutes`, `FromSeconds`. It must be a constant and it must be positive; a computed value or a bare number is a compile error rather than a window nobody can predict. ## Description {#description} ### What "finished" means, and why age alone is never enough {#finished} The window is measured from the moment a run **completed** — not from when it started, and not from when it was last touched. A run that succeeded, failed or was cancelled is finished; a run that is still executing or waiting on an event is work in progress and is out of scope entirely. This distinction is the whole safety property. A long-running workflow — an annual review, a multi-year warranty, a contract that waits on a renewal that has not come — can easily be older than any window you would pick, and it must survive. Age is only ever consulted for a run that has already reached a terminal state, so a live run cannot be selected at all. ### What goes with the run {#owned-rows} A finished run owns the rows that describe how it ran: the work items it opened, the timers governing them, the results of the steps it executed, and its transition trail. These are **structurally owned** — they describe that one run and mean nothing without it — so reaping a run reaps them together. There is no state in which the run is gone and its work items remain pointing at nothing, which is worse than either keeping or removing the lot. A run that another run still names as its parent is left alone until that child has itself been reaped. Lineage stays intact; the sweep simply picks it up on a later pass. ### ⚠ It is a CEILING on your workflow audit history {#audit-ceiling} `app.Audit.WorkflowAuditRecord.Retention` (see [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/)) sets how long the **transition trail** is kept. The trail belongs to its run, so **the run window takes it with it**: once the run is reaped its trail is gone, whatever the audit window says. That means an audit window **longer** than the run window cannot be honoured, and the compiler refuses the pair rather than quietly obeying the shorter one: ```text `app.Audit.WorkflowAuditRecord.Retention` is TimeSpan.FromDays(365), but `app.Workflow.Retention` is TimeSpan.FromDays(30) — and the run window takes the audit trail with it. A workflow audit event belongs to its run (the run is reaped, its events go too), so the longer window cannot be honoured. Raise `app.Workflow.Retention` to at least TimeSpan.FromDays(365), or lower this one. ``` An equal window is fine — the run and its trail expire together. A **shorter** audit window is also fine, and is how you keep runs longer than you keep their transition detail. If you need the trail to outlive the run, do not set a run window at all. ### Removing the block stops the reaping {#removing} `app.Workflow` is reconciled on every compile, so deleting it from source removes the policy — it does not leave the last window it ever had quietly in force. For a setting whose job is deleting data, the difference between "we stopped reaping" and "we go on reaping on a rule nobody can see any more" is the whole point. ### When to reach for it {#when} Reach for a window when runs are numerous and short-lived and their history has no ongoing value — a per-request approval, a per-order fulfilment, a notification flow. Leave it undeclared when the run IS the record: anything you would expect to look up years later, or anything whose trail answers a compliance question. Keeping data costs storage; a window you set too tight costs you the answer to a question you have not been asked yet. ## Examples {#examples} Ninety days of finished runs, kept bounded without touching anything still in flight: ```osy title="basic" test app=config-workflow-retention entity Order { [Required, MaxLength(200)] string Reference; OrderStage Stage = OrderStage.Placed; security { allow read, create, update when IsAuthenticated || IsAnonymous; } } enum OrderStage { Placed, Shipped } workflow Fulfilment { Tracks = Order.Stage; Initial = Placed; event Ship(); state Placed { subscribe Ship(); on Ship { goto Shipped; } } terminal success Shipped { } } app.Workflow = new WorkflowConfig { Retention = TimeSpan.FromDays(90) }; ``` Keeping the runs for a year but their transition detail for only a month — the audit window is *shorter*, which the run window permits: ```osy title="trail-expires-first" test app=config-workflow-trail [Principal] entity Staff { [Required, MaxLength(200)] string Name; bool IsAuditor; } app.Workflow = new WorkflowConfig { Retention = TimeSpan.FromDays(365) }; app.Audit = new AuditConfig { WorkflowAuditRecord = new AuditSurface { Read = user => user.IsAuditor, Retention = TimeSpan.FromDays(30) } }; ``` ## See also {#see-also} - [audit read access (app.Audit)](https://osysharp.com/reference/config/audit/) — `app.Audit.WorkflowAuditRecord`, the transition trail this window is a ceiling on - [Workflow.Run (start a workflow)](https://osysharp.com/reference/workflow/run/) — the run this window measures, and what reaching a terminal state means - [use](https://osysharp.com/reference/types/use/) — bringing the workflow capability into the app --- # Counter > The PLATFORM assigns this number at create and you never set it — invoice codes, ticket numbers. NOT a manual order a person rearranges (see [[ui-reordering]]). A gap-free sequence; Format turns it into a code string, and scope restarts it per parent row. ## Summary {#summary} A `Counter` assigns a **sequential number when a row is created** — the order number, the invoice code, the ticket number. The platform allocates it, so two requests creating rows at the same instant cannot receive the same value. This is not the row's identity: every entity already has an `Id`. A counter is the number a *human* uses — the one they read down the phone. ## Signature {#signature} ```osy syntax Counter = new() { Start = , // the seed; the first value assigned is Start + Increment Increment = , // default 1 Format = $"…{Value:D4}…", // optional — makes the value a formatted CODE string }; entity { [Counter()] int ; // the raw number [Counter()] string ; // the formatted code (needs a Format) [Counter(, scope = )] int ; // restarts per parent row [Counter(, scope = )] string ; // a formatted code that restarts per parent } ``` ## Description {#description} ### A plain sequence — 1, 2, 3 {#plain} Declare the counter, then tag the member with the **`[Counter]`** attribute — `[Counter(Name)]` naming the counter to draw from. You never assign it — creating the row does, and the compiler enforces it: writing a counter member anywhere (an initializer, an assignment, a bulk `Update` body) is a compile error. Reading and filtering on it are ordinary: ```osy title="an auto-assigned order number" test app=counter-declaration Counter OrderNumber = new() { Start = 1000 }; entity Order { [Counter(OrderNumber)] int Number; [Required] string CustomerName; } void NewOrder(string customer) { var o = new Order { CustomerName = customer }; // Number is assigned here — 1001 for the first order, then 1002, 1003 … } ``` Note the first value is **`Start + Increment`**, not `Start`: `Start = 1000` gives you 1001 first. Read `Start` as "the number already used", not "the number I want first". ### A formatted code — `INV-0001` {#format} `Format` is an interpolated string with a `Value` placeholder, and it turns the sequence into the code your business actually uses. Tag a `string` member to get it: ```osy title="a formatted invoice code" test app=counter-declaration Counter InvoiceNumber = new() { Start = 0, Format = $"INV-{Value:D4}" }; entity Invoice { [Counter(InvoiceNumber)] string Code; // "INV-0001", "INV-0002", … decimal Total; } ``` `:D4` is the C# format specifier for "at least 4 digits, zero-padded". Pad generously — a code that jumps from `INV-9999` to `INV-10000` will sort wrongly in every spreadsheet it ever lands in. #### What can go in the template? {#holes} Exactly three, each with an optional `:format`: | hole | fills with | |---|---| | `{Value}` | the number | | `{DateTime.UtcNow}` · `{DateTime.Now}` | the current instant, UTC — the two spellings fill identically | | `{DateTime.UtcNow.InZone()}` | that instant read as a zone's wall-clock time | Anything else is a **compile error**. It used to be copied into the value verbatim, so `$"INV-{Vaule:D4}"` printed `INV-{Vaule:D4}` on every row until somebody noticed in the data. ⚠ **A bare instant hole is UTC**, whichever way it is spelled — see [Current time (DateTime.UtcNow, DurableClock.Now)](https://osysharp.com/reference/function/current-time/). `{DateTime.Now}` once rendered the *server's local* time here, which is the wrong year for anyone reading the invoice from another zone, and wrong at a boundary nobody tests. Name the zone when the number should carry a local year: ```osy syntax Counter InvoiceNumber = new() { Start = 0, Format = $"INV-{DateTime.UtcNow.InZone(Europe/Stockholm):yyyy}-{Value:D4}" }; ``` The zone id is **unquoted**, unlike `Zone.Of("Europe/Stockholm")` in an expression — the template already lives inside a string, so a nested quote would end it. An IANA id has no spaces or brackets, so nothing is ambiguous without them. ### Counting by something other than 1 {#increment} ```osy title="a sequence that steps by ten" test app=counter-declaration Counter BatchNumber = new() { Start = 0, Increment = 10 }; // 10, 20, 30 … entity Batch { [Counter(BatchNumber)] int Seq; [Required] string Name; } ``` ### A sequence that restarts per parent {#scope} `scope` restarts the sequence for each distinct value of a reference — so each project's tickets are numbered from 1, which is what people expect when they say "ticket 3 on the Apollo project": ```osy title="ticket numbers that restart for each project" test app=counter-declaration Counter TicketSeq = new() { Start = 0 }; entity Project { [Required] string Name; } entity Ticket { [Required] string Title; Project Project; [Counter(TicketSeq, scope = Project)] int Seq; // 1, 2, 3 … within EACH project } ``` Without `scope` the numbers would be global — Apollo's first ticket might be 4,812, because Mercury used the first 4,811. With it, every project starts at 1. #### Both at once — a formatted code that restarts per parent {#scope-and-format} `scope` and `Format` combine, and the combination is the shape most businesses actually want: each customer's invoices numbered from one, in the customer-facing code: ```osy title="each organization numbers its own reports from SF-0001" test app=counter-declaration Counter ReportNumber = new() { Start = 0, Format = $"SF-{Value:D4}" }; entity Organization { [Required] string Name; } entity ExpenseReport { [Required] string Title; Organization Org; [MaxLength(20)] [Counter(ReportNumber, scope = Org)] string Number; // SF-0001, SF-0002 … per org } ``` ⚠ **A scoped counter has to read its own numbers back**, because it continues from the highest one already issued to *that* parent — and on a `string` member the column holds the code, not the number. So the format must let the number be found again, and one that does not is a **compile error** rather than a wrong number on somebody's invoice: | format | why it is refused | |---|---| | `$"SF-{DateTime.UtcNow:yyyy}"` | never prints `{Value}` — there is no number in the code to continue from | | `$"SF-{Value:D4}{DateTime.UtcNow:yyyy}"` | `{Value}` sits against a date hole: `00012026` says nothing about where the number ends. Put a separator between them | | `$"{Value}-{Value}"` | two copies of the number give two answers | None of these applies without `scope` — nothing ever reads an unscoped counter's value back, so every format that renders is legal there. ### Can I use it as the primary key? {#not-the-id} Do not use a counter as the primary key, and do not use the `Id` as an order number. They answer different questions: the `Id` identifies the row to the system, the counter names it to a person. Both exist because both are needed. ## See also {#see-also} - [entity](https://osysharp.com/reference/entity/declaration/) — the `Id` every entity already has - [constraints](https://osysharp.com/reference/entity/constraints/) — `[Unique]`, for when the value comes from outside rather than a sequence - [entity members](https://osysharp.com/reference/entity/properties/) — the member types a counter can fill --- # Diagnostics (saying something, and silencing something) > What your app says while it runs, and what the compiler says about it. The first-day mistake is reaching for a print statement — `Log.*` is dual-sided, so one call from a page lands in the browser console AND in `osy logs` under one correlation id spanning client and server. ## Summary {#summary} **Two things live here: what your app says at run time, and what the compiler says at build time.** ```osy title="one call, both sides of the wire" test app=diagnostics-index entity Order { [Required, MaxLength(40)] string Code; bool Shipped; } void ShipOrder(Order order) { Log.Information("Order {OrderCode} shipped", order.Code); order.Shipped = true; } ``` ## Description {#description} **`Log.*` is dual-sided and always available** — no dependency to declare. Called from a page it reaches the browser console *and* the app's own log, under one correlation id that spans the client call and the server work it caused, which is what makes `osy logs --tail` the first move when a page misbehaves. Both the template form and an interpolated string capture searchable fields; the interpolated form is decomposed, not flattened. See [Log.*](https://osysharp.com/reference/diagnostics/log/). **A warning you have decided about is silenced where you decided it** — [[SuppressWarning]](https://osysharp.com/reference/diagnostics/suppress-warning/) — not by turning the rule off globally. A suppression names the rule and sits at the site, so the next reader sees the decision rather than an absence. **For what a run actually did, rather than what it said**, the local area has the tools: [Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) opens a trace and jumps to the fault, and faults are captured even with tracing off. ## See also {#see-also} - [Log.*](https://osysharp.com/reference/diagnostics/log/) — the one logging call, and why it is dual-sided - [[SuppressWarning]](https://osysharp.com/reference/diagnostics/suppress-warning/) — silencing one rule at one site - [Seeing what happened when your code ran](https://osysharp.com/reference/local/seeing-what-happened/) — when the log is not enough and you want the run --- # Log.* > Write a line to your app's structured log. Both a plain template (`"Order {OrderCode} shipped", order.Code`) and an interpolated string (`$"Order {order.Code} shipped"`) capture searchable fields — the interpolated form is decomposed, not flattened. Always available; no dependency to declare. Read the lines back with `osy logs`. ## Summary {#summary} **`Log.*`** writes a line to your app's structured log — the one `osy logs` reads back. ```osy syntax Log.Information("Order {OrderCode} shipped with {Qty} items", order.Code, order.Qty); ``` A log line is not just text. The `{OrderCode}` and `{Qty}` slots become **searchable fields** on the stored line, so you can later ask for *every* line where `OrderCode` was `A-1`, rather than grepping for a substring. You do **not** declare a dependency to use it. Logging isn't network access or data access, so — unlike the HTTP and storage surfaces — there is nothing to switch on. `Log.*` is simply always there. `Log.*` works the same in **server-side code and in UI actions** — same spelling, same levels, same fields. A line written in the browser goes to the browser console *and* to your app's log, so `osy logs` shows both sides of a click together. ## Signature {#signature} ```osy syntax void Log.Verbose ([Exception e, ] string message [, values…]) void Log.Debug ([Exception e, ] string message [, values…]) void Log.Information([Exception e, ] string message [, values…]) void Log.Warning ([Exception e, ] string message [, values…]) void Log.Error ([Exception e, ] string message [, values…]) void Log.Fatal ([Exception e, ] string message [, values…]) ``` - **`message`** — a template with `{Field}` slots, an interpolated string, or a plain string. - **`values`** — one value per `{Field}` in the template, in order. Not used with an interpolated string (its holes already *are* the values). - **`e`** (optional, on any level) — an exception to attach to the line, with its stack trace. The six levels, quietest to loudest: **Verbose** (tracing detail, normally switched off) · **Debug** (detail useful while developing) · **Information** (the app's normal running commentary) · **Warning** (something is off, but the operation continued) · **Error** (an operation failed) · **Fatal** (the app cannot continue). ## Description {#description} ### Two ways to write a line — both keep the fields {#forms} The template form names its fields explicitly: ```osy title="the template form — field names written down" syntax Log.Information("Order {OrderCode} shipped with {Qty} items", order.Code, order.Qty); ``` The interpolated form reads more naturally, and captures exactly the same fields: ```osy title="the interpolated form — same fields, nothing destroyed" syntax Log.Information($"Order {order.Code} shipped with {order.Qty} items"); ``` Both render the identical message, and both store `OrderCode`/`Qty` (template form) or `OrderCode`/`OrderQty` (interpolated form) as fields you can search on. **The structure is a bonus you never pay for** — the line reads the same either way. This is worth dwelling on, because it is the opposite of what most languages do. Elsewhere, putting an interpolated string into a logger *destroys* the structure: the values are pasted into one flat string before the logger ever sees them, which is why linters warn you away from it. Here the natural spelling is also the correct one. **Field names in the interpolated form** are derived from what's in the hole: `{order.Code}` becomes `OrderCode`, `{count}` becomes `Count`. A hole that isn't a simple path — `{order.Total * rate}` — has no natural name, so it is stored positionally (`arg0`). **Which form should you use?** If a dashboard or an alert depends on a field name, use the **template form** — the name is written down, so renaming a variable can't silently change it. For everyday logging, the **interpolated form** is shorter and reads better. Both are first-class. ### Formatting a value {#formatting} A format specifier works in either form, exactly as it does elsewhere in the language: ```osy title="a format specifier, in either form" syntax Log.Information("Charged {Amount:N2} to {Card}", amount, card); Log.Information($"Charged {amount:N2} to {card}"); ``` ### A message you computed {#computed-message} If the message is a value rather than a template, it still logs — as a plain line, with no fields: ```osy title="a message you computed — a plain line, no fields" syntax var msg = BuildSummary(order); Log.Information(msg); ``` That is allowed and sometimes exactly right. But there is nothing for values to bind to, so passing extra values alongside a computed message is an error. Switch to a template when you want fields back. ### Recording a failure {#exceptions} Attach the exception itself rather than pasting its message into the text — the stack trace is stored with the line: ```osy title="attach the exception, do not paste its message" syntax try { ChargeCard(order); } catch (Exception e) { Log.Error(e, "Charge failed for {OrderCode}", order.Code); } ``` ### What you never have to pass {#ambient-context} Every line automatically carries the context it was written in: which request it belongs to (its correlation id), which app, which user, and which function was running. You never pass any of that — it is added for you, and it is what lets you pull up **every line from one request**, across everything it touched: ```bash osy logs --corr a1b2c3d4e5f6 ``` That holds even when a function pauses and resumes later: both halves belong to the same request. Lines written from background work — a scheduled task, a workflow step — carry the correlation id of the request that *started* the work, so a chain that leaves the request and comes back is still one trace. ### One click, one trace {#correlation} This is the part worth understanding, because it is what the whole surface is for. When a user clicks something, the action that runs, the log lines it writes, and every server function it calls all share **one correlation id**. So a bug that starts in the browser and ends in a server function is *one* query: ```bash osy logs --corr c-a1b2c3d4e5f6 ``` You will see the browser's lines and the server's lines interleaved, in order — not two disconnected halves. That includes the line you most want: **an action that throws is logged automatically**, at `Error`, with its exception and under that same id. You do not have to wrap your actions in `try`/`catch` to find out that one failed. ### Reading the lines back {#reading} `osy logs` reads your app's log back from the local platform: ```bash osy logs # the recent lines osy logs --tail # follow live, printing new lines as they are written osy logs --level error,warning # only these levels (exact — comma-separated means "any of") osy logs --function-name ShipOrder # only lines written while this function ran osy logs --corr a1b2c3d4e5f6 # every line from one request, across everything it touched osy logs --grep "timed out" # search the message text osy logs --side client # only the lines your app wrote in the BROWSER osy logs --side server # only the lines it wrote server-side ``` The same command exists against a deployed app as `osyrin app logs`, with the same filters — except `--tail`, which is local-only for now. ### A note on browser lines in production {#browser-lines} Lines written in the browser are sent to your app's log, so you can see what a real user's browser actually did. To keep that from becoming noise (and cost), only `Warning` and above are sent from a deployed app by default — locally you get everything. Set `Log:ClientMinimumLevel` to change it. ## Examples {#examples} Log a milestone with searchable fields, and record a failure with its exception: ```osy title="log a milestone, and a failure" test app=log entity Order { [Required] string Code; int Qty; bool Shipped; } void ShipOrder(Order order) { Log.Information("Order {OrderCode} shipped with {Qty} items", order.Code, order.Qty); order.Shipped = true; } void ChargeOrder(Order order) { try { throw new Exception("card declined"); } catch (Exception e) { // The exception rides along with the line — stack trace and all. Log.Error(e, "Charge failed for {OrderCode}", order.Code); } } ``` The interpolated form — same fields, less ceremony: ```osy title="the interpolated form captures fields too" test app=log void Audit(Order order) { var qty = order.Qty; Log.Debug($"Recomputing totals for {order.Code} ({qty} items)"); Log.Warning($"Order {order.Code} has no line items"); } ``` ## See also {#see-also} - [Http.*](https://osysharp.com/reference/http/facade/) — the outbound-HTTP surface, whose calls appear in these same logs --- # [SuppressWarning] > Accept ONE named warning about ONE declaration. Put it on whatever the finding is reported against — a function, an entity, one FIELD of an entity, a component or a component member, a workflow state or one of its members — naming the code the warning itself prints. Everything else that declaration earns still arrives, errors are never affected, and a MUST-tier lint finding is reported however it is annotated. ## Summary {#summary} **`[SuppressWarning("CODE")]`** is how you say *I read that one, and I mean it*. ```osy syntax [SuppressWarning("cost-unbounded-read")] live var everyRoom = Room.ToList(); ``` A warning tells you something about your program that is usually a mistake. Some programs are correct **and** earn one anyway. Without a way to say so, you are left choosing between changing correct code and living with a message you have to re-read and re-dismiss every build — and a warning people learn to skip past has stopped working, for your case and for the next one. ## Signature {#signature} ```text [SuppressWarning("CODE" [, "CODE"…])] ``` - **`CODE`** — the diagnostic code, exactly as the warning prints it — a compiler code (`ENUM_VALUE_REINTERPRETED`) or an `osy lint` rule id (`cost-unbounded-read`). String literals only. - Placed on **whatever the finding is reported against** — see [Where does it go?](#where). - Several codes in one attribute, or several attributes, both work. ## Description {#description} ### Where does it go? {#where} **On the thing the finding is reported against, at the granularity it names.** Every finding prints a target and a line; put the attribute on the declaration that line belongs to. All of these carry it: | the finding names… | write it on | |---|---| | an app-wide shape | the `app { }` manifest | | a function | the `void Foo(…)` declaration | | an entity, or the entity's `security { }` | the `entity Foo` declaration | | **one FIELD of an entity** (`User.Email`) | **that field** | | a component, or its page | the `component Foo()` declaration | | a component member | that `action` / `live var` / field / lifecycle hook | | a workflow state (`Flow.Pending`) | that `state` | | **a member of a state** (`Flow.Pending.Acceptance`) | **that member** — the `subscribe` slot, the `enter` / `exit` block, the `on` handler, or the `Assigned` / `Finished` milestone the finding is reported in | | a workflow event | the `event` declaration, beside its `[Authorize]` | A dotted target is the tell: `User.Email` is a **field**, so the attribute goes on the field, not on `User`. Putting it on the entity would work too — an entity's suppression covers its whole body — but it accepts more than you looked at, and the next field to earn the same finding is silenced by a decision nobody made about it. ### A MUST is not suppressible {#must} `osy lint` sorts findings into MUST / SHOULD / CONSIDER. A **SHOULD or a CONSIDER is advice**, and recording a decision about advice is exactly what this attribute is for. A **MUST is the ship gate** — `osy lint --strict` exits non-zero on one — so it stays reported however it is annotated, and the finding tells you so in a sentence rather than going quiet. That holds at every placement, a field included: widening *where* the attribute may be written never widens *what* it can silence. ### It covers ONE declaration {#scope} The suppression applies to the declaration it sits on, and to nothing else. There is deliberately no file-wide or app-wide form: you are accepting **one warning about one thing**. A file-level switch would go on silencing the same warning in code written later, by someone who never made that judgement — which is the moment a suppression stops being a decision and becomes a blindfold. ### It covers ONE code {#one-code} Naming a code silences that code. Every other warning the declaration earns — today's and tomorrow's — still arrives. That is what makes the attribute safe to leave in place: it does not turn anything off, it answers one question. There is no bare `[SuppressWarning]`. It would mean "and whatever else this earns", which is the one thing you are not in a position to agree to yet, so the compiler asks for the code instead. ### It never touches an error {#not-errors} Only warnings can be suppressed. An error says your program does not have a defined meaning; that is not a matter of opinion and there is nothing to accept. ### Say WHY, in a comment {#why} The attribute records that you decided; it cannot record what you knew. A reader six months later needs the reason, and the reason is usually a sentence: ```osy syntax // There are eleven rooms and there will never be more — this is a fixed set, not a growing table. [SuppressWarning("cost-unbounded-read")] live var everyRoom = Room.ToList(); ``` If you cannot write that sentence, the warning is probably right. ## Examples {#examples} ### Accepting the commit-agency warning {#example-commit} A board reads its whole column list on every visit. `cost-unbounded-read` is right that an unbounded read is usually a paging bug waiting to happen — and here the set is fixed by the domain, so it is not. ```osy title="a read that is unbounded on purpose" test app=diagnostics-suppress-warning [Principal] entity User { [MaxLength(255)] string Email; } entity Column { [MaxLength(80)] string Title; security { allow read, create when IsAuthenticated; } } [Page("/board")] component BoardPage() { // A board has four columns and always will — this is a fixed set, not a growing table. [SuppressWarning("cost-unbounded-read")] live var columns = Column.ToList(); render { Stack(gap: 2) { foreach (var c in columns) { Text(c.Title); } } } } ``` ### Does one suppression cover the rest of the file? {#example-scope} A suppression on one member says nothing about another. If a second member earns the same finding, it gets it — and that is the point: the first decision was about the first member. ```osy syntax [SuppressWarning("cost-unbounded-read")] live var everyRoom = Room.ToList(); // accepted live var everyBooking = Booking.ToList(); // still reported — nobody has said anything about this one ``` ### Accepting a finding about one FIELD {#example-field} `data-constraint-lets-null-through` asks a real question about a `[Unique]` field that can be absent: two rows with no value do not collide, so the constraint does not mean "every row has one". Here the field is genuinely optional, so the answer is "yes, that is what I meant" — and the finding is scoped to the field, so the attribute goes there. ```osy title="a constraint that lets null through, on purpose" test app=diagnostics-suppress-warning-field [Principal] entity User { [Unique, MaxLength(200)] string Email; [MaxLength(200)] string PasswordHash; // A referral code is optional — most people sign up without one, and two blanks are not a clash. [SuppressWarning("data-constraint-lets-null-through")] [Unique, MaxLength(40)] string? ReferralCode; security { allow read when IsAuthenticated; // Nothing to do with suppression — a credential on the [Principal] rides `Session.CurrentUser` to the // browser without it. See [app.Auth — how the platform authenticates a user of your app](https://osysharp.com/reference/security/password-auth/). deny read PasswordHash when IsAuthenticated; } } ``` Note the `?`. A bare `string ReferralCode;` is **required by its spelling**, so it has no absent case and the finding never fires on it — a suppression there would silence nothing. ### Accepting a finding about a workflow slot, or an `enter` block {#example-workflow} An invitation is answered by whoever holds the emailed link. Two findings are right to ask about that: the slot declares no `Candidates` (`workflow-slot-open-to-everyone`), and the link minted in `enter` steps around the event's `[Authorize]` (`security-callback-url-widens-an-authorize`). Both are the design here, so both are answered where they are reported — on the slot, and on the `enter` block. A state member takes the attribute exactly as a function or a field does, and so does the `state` itself. ```osy title="a slot that is open on purpose, and a link that is meant to widen the rule" test app=diagnostics-suppress-warning-workflow enum InviteStatus { Pending, Accepted, Expired } [Principal] entity Person { [MaxLength(80)] string Email; security { allow read when IsAuthenticated; } } entity Invite { [MaxLength(200)] string Email; InviteStatus Status; [MaxLength(400)] string? Link; security { allow read, create, update when IsAuthenticated; } } workflow Invitation { Tracks = Invite.Status; Autostart = true; Initial = Pending; [Authorize(u => u.Email == this.Item.Email)] event Accept(); state Pending { // Anyone holding the link may accept — the slot is open by design, not by omission. [SuppressWarning("workflow-slot-open-to-everyone")] subscribe Accept() as Acceptance { Finished { Within = TimeSpan.FromDays(14); Unfinished { goto Expired; } } } // The emailed link is the whole point: the [Authorize] above governs the in-app button, the link the mail. [SuppressWarning("security-callback-url-widens-an-authorize")] enter { this.Item.Link = Acceptance.CallbackUrl(); } on Acceptance { goto Accepted; } } terminal success Accepted { } terminal cancel Expired { } } ``` Each attribute covers the one member it sits on. A second slot in `Pending` with no `Candidates` would still be reported — that is a second decision, and nobody has made it yet. ## See also {#see-also} - [Log.*](https://osysharp.com/reference/diagnostics/log/) — writing to your app's own log, which is a different question from the compiler's. --- # Comparing entity rows > `==` on two entity references compares them by ROW IDENTITY — not by object reference, and not field by field. Two references to the same row are equal however you fetched them, so `list.Contains(row)`, `list.IndexOf(row)` and `list.Remove(row)` all find the row you mean. You never have to compare `.Id` yourself. ## Summary {#summary} Two references to the same row **are** the same row, whichever query each came from: ```osy title="two reads of one row, compared directly" test app=entity-equality entity Contact { [Required] string Name; string Email; } bool OneRowTwoReads(string name) { var a = Contact.Single(c => c.Name == name); var b = Contact.Where(c => c.Name == name).First(); return a == b; // true — two reads, one row } ``` `a` and `b` were fetched by two separate queries and are still equal. **You do not have to write `a.Id == b.Id`.** ## Signature {#signature} ```osy syntax a == b // true when both references are the SAME ROW a != b // the negation a == null // no row — an unset reference, or a lookup that found nothing ``` ## Description {#description} ### An entity compares by identity, a class by value {#why} An entity is a **row in a table**. It has an identity of its own, that identity is what the platform stores, and it is what `==` asks about. So the rule cuts both ways: - The **same row read twice** is equal to itself — through two queries, in two orders, on the server or on the client. Nothing about how you got hold of it changes the answer. - **Two different rows are never equal**, however identical their columns. Two rows are two rows. ```osy title="identical columns, still two rows" test app=entity-equality bool TwinsAreOneRow() { var twins = Contact.Where(c => c.Name == "Twin").OrderBy(c => c.Id).ToList(); return twins[0] == twins[1]; // false — same name, same email, two rows } ``` A [class](https://osysharp.com/reference/class/equality/) has no identity to compare, so its **contents** are the answer instead. That is the only difference between the two rules, and it follows from what each thing is. ### Contains, IndexOf and Remove all find the row {#collections} Every list operation that takes an element compares with the same `==`, so over a list of rows each of them is asking *"is this the same row?"* — and each of them gets it right, **including when the list came from one query and the row from another**: ```osy title="asking a list about a row you already hold" test app=entity-equality string Positions(Contact one) { var ordered = Contact.OrderBy(c => c.Name).ToList(); return "at=" + ordered.IndexOf(one) // its position, or -1 + " has=" + ordered.Contains(one) // is it in this list at all + " gone=" + ordered.Remove(one) // take that row out of the list + " left=" + ordered.Count; } ``` `one` was never read by the query that built `ordered`, and all three still identify it. The same holds on the client: a row a screen is holding — off a [`live var`](https://osysharp.com/reference/ui/reactivity/), or handed to an action by a `foreach` — is the same row the list holds, and these three operations say so. ### FindIndex over .Id is not wrong, only longer {#by-id} This is the same question, asked the long way round: ```osy title="the two spellings, and they agree" test app=entity-equality bool BothWaysAgree(Contact one) { var ordered = Contact.OrderBy(c => c.Name).ToList(); return ordered.FindIndex(c => c.Id == one.Id) == ordered.IndexOf(one); // always true } ``` If you have written the `FindIndex` form, **nothing is broken** — it returns the same index, and it is a perfectly readable thing to have written. It is simply not needed: `IndexOf` already compares by identity, so the lambda is restating the rule the language applies anyway. Reach for [`FindIndex`](https://osysharp.com/reference/query/in-memory-linq/) when you genuinely cannot hold the element — you have an id off a URL, a name typed by a user, or any other *description* of the row rather than the row. That is what it is for. ## See also {#see-also} - [entity](https://osysharp.com/reference/entity/declaration/) — what a row is, and how you read one back - [Comparing classes](https://osysharp.com/reference/class/equality/) — why a `class` compares by its fields instead - [LINQ over a local list](https://osysharp.com/reference/query/in-memory-linq/) — `IndexOf`, `FindIndex` and the rest of the list verbs - [Child collections (navigating a relation)](https://osysharp.com/reference/query/collections/) — a parent's child collection, which holds rows the same way --- # ConcurrencyCheck > Refuses an update whose value was changed by somebody else since this writer read it. Field-scoped — two people editing different fields of one record are not in conflict — and raised as a ConflictException the app can catch. ## Summary {#summary} `[ConcurrencyCheck]` refuses an update whose value was changed by somebody else **since this writer read it**. It is what stops the last save winning silently — the failure mode where two people open the same record, both save, and the first one's work disappears with nothing said to either of them. It is **field-scoped**: only the fields a write actually sets are checked, so two people editing different fields of the same record both succeed. ## Signature {#signature} ```osy syntax [ConcurrencyCheck] // on the ENTITY — guards every property entity Case { … } entity Case { [ConcurrencyCheck] decimal? Amount; // …or on ONE property } ``` ## Description {#description} ### What it does A guarded update only lands if the row still holds the value this writer read. If it does not, the write is refused and nothing is written — the other person's value stands, and yours is still in front of you to re-apply. The refusal is a [ConflictException](https://osysharp.com/reference/function/throw/), so you catch it exactly as you catch any other conflict — and then say what you want done with the write that failed: ```osy syntax try { c.Amount = amount; UnitOfWork.Commit(); } catch (ConflictException e) { message = e.Message; UnitOfWork.Discard(); } ``` ### Why didn't my catch stick? {#abandon-or-repair} Catching the refusal does not un-stage the write that caused it. The row is still holding your value, and the platform commits once more when your function ends — so **the same refusal is raised a second time**, from a place no `try` of yours can reach. That is not an accident: it is what lets a catch **repair** the value and have the repair committed for you. So the catch has to say which of the two you meant, and there are only two: | you want | write this in the catch | |---|---| | **abandon** the write — show the message, keep the other person's value | `UnitOfWork.Discard();` | | **retry** it — resolve the conflict and save your value after all | set the field again; it commits when the function ends | Leave out both and the run ends with the refusal you already handled. The second one says so, and names these two. It is the same rule a refused CONSTRAINT follows, worked through in full at [[function-throw#the-refused-row]]. ### Field-scoped, and why that matters Only the columns a write SETS are checked. If Anna changes `Amount` and Bo adds a note to the same record, neither is refused — they were never in conflict. The alternative, refusing on any change to the row, is simpler and worse: it refuses writes that are not conflicts, and a conflict message that fires when nothing is wrong is one people learn to click past. That is the failure this scoping exists to avoid. ### It is one statement, so there is no window The check rides the UPDATE's own `WHERE`: ```sql SET amount = @amount WHERE id = @id AND amount IS NOT DISTINCT FROM @was ``` Deciding and writing are the same statement, so nothing can change between them. The two designs that look equivalent both have a window: re-reading the row and comparing leaves a gap before the write, and consulting the audit trail is worse still — the trail is written *after* the commit, so a competing writer's entry may not be there yet. ### What "since it was read" means across a page load The value compared against is what **this writer read**, not what the row holds now. That distinction is the whole feature: a person holding a page across a round trip is the only writer who can be stale, and their belief is pinned when they read it, so it survives being resumed later. ### The message The refusal names the fields it refused, and **names who changed the row and when** when there is somebody to name — that comes from the entity-change audit trail. An anonymous write records no user, so the sentence falls back to "somebody else". If your app turns the trail off, the refusal still works and the sentence loses the name; a lint rule (`security-concurrency-check-without-its-trail`) says so at compile time. ### What it does not do It does not tell you somebody else has the record open — that is presence, a different mechanism. It does not lock anything: nobody is blocked from editing, and a conflict is only possible when two writes genuinely overlap on one field. ## Examples {#examples} ```osy title="guard the whole record" test app=concurrency-check [ConcurrencyCheck] entity Case { [Required, MaxLength(40)] string Reference; decimal? Amount; [MaxLength(200)] string? Owner; security { allow read, create, update when IsAuthenticated || IsAnonymous; } } ``` ```osy title="catch the refusal and abandon the failed write" test app=concurrency-check string Save(Guid id, decimal amount) { var c = Case.Single(x => x.Id == id); try { c.Amount = amount; UnitOfWork.Commit(); return "saved"; } catch (ConflictException e) { UnitOfWork.Discard(); // …or set c.Amount again, to save yours after all return e.Message; } } ``` ## How do I test it? {#testing} A conflict needs **two writers**, and a test body is one — so the thing to stage is not two readers, it is a **settle in between**. Everything one function call stages is a single unit of work however many times it writes, so the other person's change has to reach the database before yours is attempted: 1. read the row into a variable — this is what *you* believe it says; 2. make the other person's change and `UnitOfWork.Commit()` it; 3. write through the variable from step 1 and commit. Step 2's commit is the whole trick. Without it there is only one writer and nothing is refused. ⚠ **Two things that look like they matter and do not.** Reading the row twice does not help — both reads give you the same tracked row, so it is still one writer. Neither does `runas`, in either spelling: a conflict is about *when* a write settled, never about *who* settled it, and staging one under two principals stages the same single writer twice. ```osy title="the model under test" test app=concurrency-conflict [ConcurrencyCheck] entity Ledger { [Required, MaxLength(40)] string Code; decimal? Amount; security { allow read, create, update when IsAuthenticated || IsAnonymous; } } /// The OTHER person's save. void MoveAmount(Guid id, decimal amount) { var l = Ledger.Single(x => x.Id == id); l.Amount = amount; } ``` ```osy title="staging the two writers" run app=concurrency-conflict [TestFixture] void Seed() { var l = new Ledger { Code = "L-1", Amount = 100 }; } [Test(Seed)] void A_stale_write_is_refused_and_the_other_persons_value_stands() { var mine = Ledger.Single(x => x.Code == "L-1"); // 1 — what I believe it says MoveAmount(mine.Id, 250); UnitOfWork.Commit(); // 2 — …and somebody else's save lands string refused = ""; try { mine.Amount = 999; UnitOfWork.Commit(); } // 3 — my save, against what I read catch (ConflictException e) { refused = e.Message; UnitOfWork.Discard(); } Assert.Contains("changed", refused); Assert.Equal(250, Ledger.Single(x => x.Code == "L-1").Amount); } // …and the same test WITHOUT step 2's commit refuses nothing, which is what makes that line the mechanism // rather than a detail of this example. [Test(Seed)] void With_no_settle_between_them_there_is_only_one_writer() { var mine = Ledger.Single(x => x.Code == "L-1"); MoveAmount(mine.Id, 250); string refused = ""; try { mine.Amount = 999; UnitOfWork.Commit(); } catch (ConflictException e) { refused = e.Message; UnitOfWork.Discard(); } Assert.Equal("", refused); } ``` `Assert.Throws(() => …)` works too, and it does step 2 for you — it settles whatever is already staged before running its body. That is convenient and it is also why a test can pass under `Assert.Throws` and prove nothing about the same code written with `try`/`catch`: the assertion supplied the missing commit. ## See also {#see-also} - [constraints](https://osysharp.com/reference/entity/constraints/) — the other per-member rules, checked when the row is written - [throw](https://osysharp.com/reference/function/throw/) — `ConflictException` and the closed set of fault types - [try / catch / finally](https://osysharp.com/reference/function/try-catch/) — catching it - [entity](https://osysharp.com/reference/entity/declaration/) — where the attribute goes --- # The data model (entities and their rules) > An entity is a table — and the rules that are true about it. Not just its columns: what must hold for a row to exist, and who may see or change it, live ON the entity, next to the data, and are enforced for every path that ever touches it. This is where an app starts, and getting it right is most of getting the app right. ## Summary {#summary} An **entity** is a table of rows your app stores. But the declaration is not a list of columns — it is everything that is **true** about those rows: ```osy title="a table, and what is true about it" test app=entity-index entity Order { [Required, Unique, MaxLength(20)] string Code; // the shape … [Required] decimal Total; bool Cancelled; invariant Total >= 0; // … what must hold for a row to exist … security { allow create, read, update when IsAuthenticated || IsAnonymous; } // … and who may touch it } ``` Three different questions, answered in one place: **what shape is a row** ([entity members](https://osysharp.com/reference/entity/properties/)), **what makes a row valid** ([constraints](https://osysharp.com/reference/entity/constraints/) · [invariant](https://osysharp.com/reference/entity/invariants/)), and **who may see or change it** ([The security model](https://osysharp.com/reference/security/index/)). They are enforced for **every** path that ever touches the table — this function, the next one, the UI, a workflow, an import you write in six months. There is nowhere to write a row that goes around them, so there is nowhere to forget. ## Description {#description} ### What the platform gives every row {#free-columns} You never declare an identifier, and you never declare an audit trail: | Member | What it is | |---|---| | `Id` | the row's identity, a `Guid`, assigned for you | | `CreatedAt` · `ModifiedAt` | when the row was written, and last changed | | `CreatedBy` · `ModifiedBy` | **who** — the signed-in principal, not a value your code passes | `CreatedBy` is worth pausing on, because it is not just an audit column: it is stamped from the **security principal**, so a rule may authorise on it. That is how ownership works with **no owner field and nothing in your code that assigns one**: ```osy title="ownership, declared once, with no owner field" test app=entity-index-owner [Role] enum AppRole { Authenticator, Member } [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read where Id == user.Id; } } entity Note { [Required, MaxLength(200)] string Title; security { allow create when IsAuthenticated; allow read, update, delete where CreatedBy == user.Id; // ← ownership, in one line } } ``` Every reader of `Note` now sees only their own — including `Note.Count()`, which honestly means *"how many are mine"*. ### What an unset member reads back {#optional} **The declaration decides**, and it reads exactly as C# does: ```osy title="what the type spelling decides about being unset" syntax decimal Amount; // has an honest zero → unset reads 0. decimal? Amount; // `?` → may be unset. Unset reads null. string Title; // NO honest zero → REQUIRED. You must supply it. ``` Whether a member is required is carried by its **type spelling** — full model in [Optional and required members](https://osysharp.com/reference/types/optional-and-required/); the shapes are: | Type | Bare (no `?`, no default) | |---|---| | `int` `long` `double` `decimal` `bool` `TimeSpan` — an **honest zero** | reads its zero (`0`, `false`, `0m`); never null | | `string` `DateTime` `DateOnly` `TimeOnly` `Guid` `Json` `RichText` `Markdown` `Vector` `byte[]`, any **enum** — **no** honest zero | **REQUIRED** — you must supply it | | an entity reference (`Customer Owner;`) | **optional** — reads `null`; `[Required]` demands it | | any `T?` (`int?` `string?` `DateTime?` …) | optional — reads `null` | The reason those types have no zero is worth a sentence: the year `0001` is not a date anybody meant (it sorts first and matches `Due < today`), all-zero bits is not a `Guid` anyone assigned, and `default(string)` is `null`, not `""` — an empty string is a value someone *typed*, not the absence of one. Rather than invent a value it would then have to answer questions about, the platform **requires** you to supply one. Say `?` (`DateTime? Due;`) when "maybe unset" is genuinely what you mean, or give a default (`string Tag = "";`) when the empty value really is the right starting point. **A required member is checked when the value becomes real** — for an entity, at **commit**: `new Ticket {}` compiles (an empty draft is a normal state — a create-form binds inputs to fill it), and the row is refused at save if a required member is still unset, naming it. `[Required]` on a *reference* opts that one exception into the same rule. It is also the **only** constraint that rejects an unset value. `[MaxLength]`, `[Unique]`, `[Pattern]` and the rest all let one through, because "no value" is not a violation of "at most 20 characters" ([constraints](https://osysharp.com/reference/entity/constraints/)). **The consequence to know about.** An [invariant](https://osysharp.com/reference/entity/invariants/) reads a member, and a member that *can* be unset reads back `null` — so an invariant over an optional member is asking a question about a value that may not be there: ```osy title="an invariant over an optional member quietly makes it mandatory" syntax decimal? Total; // may be unset … invariant Total >= 0; // … and the invariant reads it — so a row with no Total is REFUSED ``` That has quietly made `Total` mandatory. If a member takes part in an invariant, either give it a type that always has a value (`decimal Total;` — the invariant then holds trivially on `0`), mark it `[Required]` (say what you mean), or guard the invariant with `when` so it only applies to the rows that have the value. ### Where do I write a rule — on the member, or on the row? {#rules} Two kinds, and the distinction is not academic — it decides where you write the rule: - A **constraint** speaks about **one member**: `[Required]`, `[Unique]`, `[MaxLength(n)]`, `[Min]`/`[Max]`, `[Pattern]`. ([constraints](https://osysharp.com/reference/entity/constraints/)) - An **invariant** speaks about **the whole row** — a relationship *between* members, optionally guarded so it applies only to the rows it should. ([invariant](https://osysharp.com/reference/entity/invariants/)) ```osy title="one member, versus the whole row" test app=entity-index entity Product { [Required, MaxLength(80)] string Name; // a constraint: about Name alone bool IsPerishable; int ShelfDays; invariant ShelfDays <= 30 when IsPerishable // an invariant: about the ROW — two members, conditionally message "Perishable items can have at most 30 shelf days."; security { allow create, read, update when IsAuthenticated || IsAnonymous; } } ``` Both are enforced **when the row is written**, by the database — not by the function that happens to be writing it. So a violation arrives as an ordinary `ValidationException` that a caller can catch ([try / catch / finally](https://osysharp.com/reference/function/try-catch/)), and the faulted write leaves nothing behind: ```osy title="the rule holds, and the bad row does not survive" run app=entity-index [Test] void A_row_that_breaks_its_invariant_is_never_written() { Assert.Throws(() => new Product { Name = "Milk", IsPerishable = true, ShelfDays = 90 }); Assert.Empty(Product.ToList()); } [Test] void A_member_left_unset_reads_back_its_zero() { var product = new Product { Name = "Salt" }; // IsPerishable and ShelfDays never set var stored = Product.Single(p => p.Name == "Salt"); Assert.Equal(0, stored.ShelfDays); // int → 0, exactly as a C# field Assert.False(stored.IsPerishable); // bool → false } ``` The `?` is how you get the other behaviour — and it is the difference between "the shelf life is zero days" and "nobody has recorded a shelf life". A type with no meaningful zero is optional whether you write the `?` or not: ```osy title="`?` opts out of the zero; a date has no zero to opt out of" run app=entity-index entity Delivery { [Required] string Reference; int Attempts; // has a zero → unset is 0 int? WeightGrams; // opted out → unset is null DateTime? ArrivedAt; // no zero → optional (`?`), so unset reads null (a bare DateTime would be required) security { allow create, read, update when IsAuthenticated || IsAnonymous; } } [Test] void The_question_mark_is_what_distinguishes_no_value_from_zero() { var delivery = new Delivery { Reference = "D-1" }; // nothing else set var stored = Delivery.Single(d => d.Reference == "D-1"); Assert.Equal(0, stored.Attempts); // zero attempts — a real, countable fact Assert.Null(stored.WeightGrams); // nobody weighed it — a different fact Assert.Null(stored.ArrivedAt); // and a date never has a zero to fall back to } ``` ### Relations: the child points up, the parent reads down {#relations} A child holds a reference to its parent — that member **is** the foreign key. The parent reads its children back through a **collection** member: ```osy title="both directions, declared once" test app=entity-index-rel entity Invoice { [Required, Unique, MaxLength(20)] string Number; [ForeignKey(Invoice)] Line[] Lines; // the parent reads DOWN security { allow create, read, update when IsAuthenticated || IsAnonymous; } } entity Line { [Required] Invoice Invoice; // the child points UP — this is the FK [Required, MaxLength(80)] string Description; decimal Amount; security { allow create, read, update when IsAuthenticated || IsAnonymous; } } ``` **Read children through the collection — never with a query filtered by the foreign key.** `invoice.Lines` is the navigation; `Line.Where(l => l.Invoice == invoice)` is you re-implementing it by hand, and worse: ```osy title="navigate the graph; do not re-query it" run app=entity-index-rel [Test] void A_parent_reads_its_children_through_its_collection() { var invoice = new Invoice { Number = "INV-1" }; var a = new Line { Invoice = invoice, Description = "Design", Amount = 100m }; var b = new Line { Invoice = invoice, Description = "Build", Amount = 250m }; var found = Invoice.Single(i => i.Number == "INV-1"); Assert.Equal(2, found.Lines.Count); Assert.Equal(350m, found.Lines[0].Amount + found.Lines[1].Amount); } ``` **A collection has no order.** It is a set of rows, exactly as a table is — `invoice.Lines[0]` is *a* line, not the first one you added, and it may differ between runs. When the order matters, ask for it: query the children with an [`OrderBy`](https://osysharp.com/reference/query/ordering/), and you get the order you asked for. `[Required]` on the reference is how you say a child **cannot exist without its parent** — an orphan then becomes a violation rather than a stray row. See [relations](https://osysharp.com/reference/entity/relations/), and [Include (pre-loading relations)](https://osysharp.com/reference/query/include/) for pre-loading a graph you are about to walk. ### An entity is stored; a `class` is not {#class} Declare a **`class`** when the value only ever lives in memory — a computed result, a payload you assemble, a shape you return. It has no table, no `Id`, no audit columns, and no `security { }`, because there is nothing stored to secure. The test is simply: *does a row of this outlive the request?* If yes, it is an entity. See [class methods](https://osysharp.com/reference/class/methods/). ### Do I write migrations when the model changes? {#evolution} You do not write migrations. `osy compile` reconciles the database with your source, and the two directions are deliberately not symmetric: - **Adding is applied.** A new entity, a new member, a new index — the schema moves, and it moves quietly. - **Removing is *proposed*, not executed.** Delete a member from your source and the column is **not** dropped. The compile reports it as a proposed drop and **keeps the data**; dropping it takes an explicit acknowledgement, and in **production** an unacknowledged drop is a hard error rather than something that happens while you are not looking. That asymmetry is the platform refusing to destroy data on the strength of a deletion you may not have meant. It is not a gap in the tooling — it is the tooling declining to be clever with the one thing it cannot undo. ### Why so much hangs off the entity design {#the-work} Most of designing an Osy# app is designing its entities, because so much hangs off them: - your **queries** are over them, and the security rules are compiled *into* those queries ([Querying data](https://osysharp.com/reference/query/index/)); - your **functions** contain no authorization code, because the entity's rules already do that job ([Functions (the unit of work)](https://osysharp.com/reference/function/index/)); - your **UI** names an entity and gets its data. Time spent getting the model and its rules right is not preparation for the work. It is most of the work. ## See also {#see-also} - [entity](https://osysharp.com/reference/entity/declaration/) — declaring one, and what you get for free - [entity members](https://osysharp.com/reference/entity/properties/) — the members, the types, and optional-by-default - [relations](https://osysharp.com/reference/entity/relations/) — references, collections, and the FK query you should not write - [constraints](https://osysharp.com/reference/entity/constraints/) — `[Required]` · `[Unique]` · `[MaxLength]` · `[Min]`/`[Max]` · `[Pattern]` - [invariant](https://osysharp.com/reference/entity/invariants/) — a rule about the whole row - [entity Sub : Base](https://osysharp.com/reference/entity/inheritance/) — `entity Sub : Base`, and what a subtype does and does not carry - [sealed](https://osysharp.com/reference/entity/sealed/) — how a type says no one may derive from it - [enum](https://osysharp.com/reference/enum/declaration/) — a closed set of values - [Counter](https://osysharp.com/reference/counter/declaration/) — a sequence the platform hands out - [The security model](https://osysharp.com/reference/security/index/) — the rules that live on the entity, and why they are in the query - [Querying data](https://osysharp.com/reference/query/index/) — reading the model back --- # [FrontMatter] — a document's header as typed data > `[FrontMatter]` binds a member to a key of the entity's markdown document's front-matter — the `---` header at the top of the file. Assigning the document fills those members in, so a document's header becomes ordinary, queryable app data rather than an opaque block, and a required member makes its key mandatory. ## Summary {#summary} Markdown documents often begin with a `---` header: ```text --- title: Getting started summary: How to create your first project. stability: stable --- ## Overview … ``` For a document that header is rarely "metadata". It is usually most of the **application's data** — the title is the navigation, the summary is the search snippet, the tags are the facets. `[FrontMatter]` says so: ```osy syntax entity DocPage { [FrontMatter] string Title; [FrontMatter] string? Summary; Markdown Body; } ``` Assign `Body` and those members fill in. They are ordinary members, so everything else about them is ordinary too: you can query them, index them, put them in a grid, secure them. ## Signature {#signature} ```osy syntax [FrontMatter] ; // key = the member name, camelCased [FrontMatter("")] ; // key named exactly ``` ## Description {#description} ### Which key a member takes {#key} A bare `[FrontMatter]` derives the key from the member name by **camelCasing** it. Osy# members are PascalCase and front-matter keys conventionally are not, so this is usually all you need: | Member | Key | |---|---| | `Title` | `title` | | `FormatVersion` | `formatVersion` | | `DeprecatedBy` | `deprecatedBy` | When a key does not follow that convention — or when the member has to be called something else — name it exactly: ```osy title="naming a key that the camelCase rule would miss" syntax [FrontMatter("format-version")] int? Version; ``` That form is also the answer for a key called `id`. Every entity already has an `Id`, so a member cannot be named that; call it something else and name the key: ```osy title="the key called id, which no member may be named" syntax [FrontMatter("id")] string Slug; ``` ### Which document it reads {#document} The entity's `Markdown` member. You do not name it, because an entity has one document in the ordinary case and repeating its name on every key would be ceremony. An entity with **no** `Markdown` member is a compile error — there is nothing to read. An entity with **more than one** is also a compile error, naming both, because guessing which document was meant would be a coin flip you never see. ### What binding does, and does not do {#binding} **It fills in declared members, on assignment.** Every write of the whole document — `page.Body = text` — re-reads the header and sets each bound member. **A key the document omits CLEARS its member.** A member says what the document says *now*, not what an earlier document said. This is why a key that may be absent should be declared optional: ```osy title="a key the document may omit must be optional" syntax [FrontMatter] string? Stability; // the document may not carry it ``` **A required member makes its key mandatory.** This is the useful consequence of the same rule: declare `[FrontMatter] string Title;` without the `?` and a document that omits `title` is refused at commit, with `Title` named. The declaration is the schema — front-matter that is checked rather than merely stored. **A key you did NOT declare is preserved, untouched.** The header is kept whole; declaring three of its ten keys binds three and leaves the other seven exactly as written. A reader that quietly dropped what it did not understand would corrupt the document it read. ### Types {#types} The header is YAML, so its ordinary shapes work: quoted and unquoted strings, folded blocks (`summary: >`), flow sequences (`tags: [a, b]`), block sequences, numbers, booleans, and an explicit `null`. | Declared as | Takes | |---|---| | `string` | a scalar (a folded block arrives as one line) | | `int` / `decimal` / `bool` / `DateTime` / `Guid` | a scalar that parses as one; anything else leaves the member unset | | a child collection | a list-valued key, one **row** per item — see below | | `Json` | a list-valued key, keeping its items as a JSON array | An explicit `null` (`deprecatedBy: null`) is *nothing*, not the text "null". ### A list-valued key {#list-key} `tags: [ui, authoring]` is a list, and a list of what you want to *query* is a set of rows. Bind it to a child collection and each item becomes one: ```osy title="a list-valued key, bound to child rows" syntax entity DocPage { [FrontMatter] [ForeignKey(Page)] DocTag[] Tags; Markdown Body; } entity DocTag { DocPage Page; [MaxLength(80)] string Name; } ``` The rows are ordinary child rows, so the things you wanted them for work with nothing extra: ```osy title="querying those rows like any other child" syntax DocPage.Where(p => p.Tags.Any(t => t.Name == "ui")).ToList() ``` The element entity must have **exactly one** scalar member — the one each item becomes. None, or more than one, is a compile error naming them, because there would be nothing to put the item in or no way to tell which member was meant. The collection must be a real `[ForeignKey]` child collection: a bare `DocTag[]` is an in-memory projection with no rows behind it, so binding one is a compile error too rather than a write that quietly goes nowhere. Re-assigning the document **reconciles**: an item that is still there keeps its row (and its id, so anything pointing at it survives), an item that arrived is created, one that is gone is deleted, and a key the new document omits empties the collection. A repeated item is one row — a set of tags is a set. A scalar is a one-item list, so `tags: ui` works. Use `Json` instead when the items are only ever read together and never queried one by one. A malformed header binds nothing rather than failing the write. Front-matter is content — hand-written, and sometimes agent-written — and a mistyped header should still store its document. ### Reading back {#reading-back} Nothing changes about how you read the document itself: `Body` still returns the markdown, and [Markdown — rendering markdown text](https://osysharp.com/reference/ui/markdown/) renders it. ### Importing documents {#importing} Assigning the member is what runs all of this, so anything that assigns it works — including a data file. A document can be given inline, or named as a file beside the data file, which is how a real corpus arrives: ```json { "entity": "DocPage", "key": "Slug", "files": { "Body": "" }, "rows": [ { "Body": "pages/controls.md" }, { "Body": "pages/slots.md" } ] } ``` Two things about that are worth knowing: - **A document's file reference brings its TEXT**, not a stored path. Unlike an image column — which stores the bytes and records where they were put — a document has no path; it becomes sections. So it needs no `public/` prefix. - **The rows carry no `Slug`.** A page's identity is its own `id:` key, and the import reads the key from the document's header when the row does not give it. That is what makes re-importing a corpus converge instead of doubling it, and it keeps one fact in one place — the document is the thing that is true. If neither the row nor the header carries the key, the import says so and names both places it looked. ## Examples {#examples} A page whose header is its data — the title drives the nav, the summary the listing, and both are queryable: ```osy title="a docs page" test app=entity-front-matter entity DocPage { [FrontMatter("id")] [MaxLength(200)] string Slug; [FrontMatter] [MaxLength(200)] string Title; [FrontMatter] string? Summary; [FrontMatter] [MaxLength(50)] string? Stability; [FrontMatter] [ForeignKey(Page)] DocTag[] Tags; [MaxLength(50)] string Area; Markdown Body; security { allow create, read, update when IsAuthenticated || IsAnonymous; } } entity DocTag { DocPage Page; [MaxLength(80)] string Name; security { allow create, read, update, delete when IsAuthenticated || IsAnonymous; } } // `Title` and `Slug` are required, so every document must carry `title:` and `id:`. void Publish(string area, string markdown) { new DocPage { Area = area, Body = markdown }; } DocPage[] Preview() => DocPage.Where(p => p.Stability == "preview").ToList(); // `tags: [ui, …]` became rows, so a facet is an ordinary query. DocPage[] Tagged(string tag) => DocPage.Where(p => p.Tags.Any(t => t.Name == tag)).ToList(); ``` ## See also {#see-also} - [Markdown — rendering markdown text](https://osysharp.com/reference/ui/markdown/) — rendering the document the header belongs to. - [entity members](https://osysharp.com/reference/entity/properties/) — declaring members, and what optional means. - [entity](https://osysharp.com/reference/entity/declaration/) — the entity the members live on. - [Where / Single / Count](https://osysharp.com/reference/query/where/) — querying by a bound member, like any other. --- # constraints > The per-member rules the database enforces — Required, Unique, MaxLength/MinLength, Min/Max, Pattern, and the storage-shaping Immutable, Precision and MaxBytes. They are checked when the row is written, so a bad row cannot reach the database from any code path. ## Summary {#summary} Constraints are per-member rules enforced **when the row is written**. They are not form validation you can forget to call: a row that breaks one cannot reach the database, whatever code path tried to write it — a function, an import, a test, an API call. ## Signature {#signature} ```osy title="the per-member rules, and where each one goes" syntax [Unique(, )] // …or over a COMBINATION, declared on the entity entity { [Required] ; // must be present [Unique] string ; // no two rows may share a value [MaxLength()] string ; // bounded text [Min(), Max()] int ; // an inclusive numeric range [Pattern("")] string ; // must match } ``` Every constraint takes an optional **message** as its last argument — what the user is told when the rule refuses them: ```osy title="giving a constraint the message the user is told" syntax [Pattern("", "")] string ; [MaxLength(, "")] string ; [Required("")] ; [Unique("")] string ; // shown when the value collides with another row ``` …including the **entity-level composite** form, where the message goes last, after the members: ```osy title="a message on a combination — the members first, the sentence last" syntax [Unique(, , "")] entity { … } ``` `[Unique]` is the one whose default wording helps least — a collision otherwise surfaces as the raw index name — so its message is worth writing: `[Unique("That slug is already taken.")]`. ## Description {#description} ### Which constraint attributes are there? {#the-constraints} | Attribute | Rule | On a null value | |---|---|---| | `[Required]` | the member must be present when the row is written | **this is the one that rejects null** | | `[Unique]` | no two rows may hold the same value | passes — nulls do not collide | | `[MaxLength(n)]` · `[MinLength(n)]` | text is at most / at least `n` characters | passes | | `[Min(n)]` · `[Max(n)]` | an **inclusive** numeric range | passes | | `[Pattern("…")]` | text matches the regular expression | passes | | `[Immutable]` | may be set on create, but **never updated** | passes (it governs updates, not presence) | | `[Precision(p, s)]` | a decimal stored with `p` total digits and `s` after the point | passes | | `[MaxBytes(n)]` | the value's stored size is at most `n` bytes | passes | Read that last column carefully: **every constraint except `[Required]` lets null through.** That is the correct behaviour — "if there is a value, it must look like this" is a different rule from "there must be a value" — but it surprises people. If a code must be present *and* well-formed, say both: ```osy title="present AND well-formed needs both" test app=entity-constraints entity Product { [Required, Pattern("^[A-Z]{3}$")] string Code; // must exist, and must be three capitals [Pattern("^[A-Z]{3}$")] string AltCode; // may be absent; if present, must match } ``` **Give a `[Pattern]` a message.** Every other constraint refuses in words a person can act on — *"Email is required"*, *"Name is too long"*. A pattern refuses with the regular expression, which explains nothing to the person reading it: ```osy title="say what the shape means" test app=entity-constraints-message entity Product { [Required, Pattern("^[A-Z]{3}$", "must be three capital letters")] string Code; } ``` ### Can I stack several on one member? {#combining} Attributes stack, in one bracket or several — whichever reads better: ```osy title="the full constraint set" test app=entity-constraints entity Coupon { [Required, Unique, MaxLength(20)] string Code; // present, one of a kind, bounded [Min(1), Max(100)] int PercentOff; // inclusive: 1 and 100 both pass [MaxLength(500)] string Notes; // optional, but bounded when given } ``` ### `[Required]` on a reference forbids an orphan {#required-reference} `[Required]` works on a [reference](https://osysharp.com/reference/entity/relations/) too, and it is how you say "this child cannot exist without its parent": ```osy title="a child that cannot be orphaned" test app=entity-constraints entity Order { [Required] string Code; } entity LineItem { [Required] Order Order; // a line with no order is a violation, not a stray row decimal Amount; } ``` ### `[Unique]` is enforced by the database {#unique} `[Unique]` is a real unique index, not a check-then-insert in application code. That distinction matters under concurrency: two requests racing to claim the same coupon code cannot both win, because the second one is rejected by the database rather than by a check that already passed. ⛔ **AND A SWAP BETWEEN TWO EXISTING ROWS IS REFUSED — the whole commit rolls back, silently.** This is the one interaction an ordered list actually performs, and it is the opposite of what most people assume, so it is worth stating plainly: ```osy syntax title="this does not work, and nothing on screen says why" [Unique] int Position; // …then, in an action: int mine = job.Position; job.Position = above.Position; // ← both rows now hold the same value for an instant above.Position = mine; UnitOfWork.Commit(); // ← the index refuses; NOTHING is written ``` A unique INDEX is checked per statement, not at commit, so the intermediate state where two rows share a value is rejected even though the state you were committing is legal. **Measured**: the two rows come back unchanged, and before 2026-08-29 the refusal reached nobody — no error, no banner, no fault in the test. It now surfaces in a failing test as `action 'MoveUp' failed: Constraint violation: 'Job.Position' must be unique`, but the write still does not land. **So for a position column, do one of these:** | | | |---|---| | **leave it un-`[Unique]`** | the ordinary answer. A rank has no meaning in a gap or a repeat beyond "which comes first", and nothing else depends on it being distinct. | | **write the midpoint instead of swapping** | `job.Position = (above.Position + below.Position) / 2m` over a `decimal` — one row changes, so no two rows ever collide. This also stops a move rewriting the whole tail. | ⚠ **`[Unique]` is not deferrable today, and that is why.** Foreign keys are (they are emitted as deferrable constraints); `[Unique]` is emitted as a `CREATE UNIQUE INDEX`, and Postgres cannot defer an index. Making it deferrable would make the swap above work as written — it is a real option and it is not built. **Over a COMBINATION of members, write it on the entity** — `[Unique(A, B)]` above the declaration, naming two or more members. It is the same real unique index, over the pair — **and it takes the same optional message, written last**: `[Unique(A, B, "…")]`. That is one form, not two, and it is the one to reach for. Without the message the person is shown the index's own words; with it, they are told what they did: ```osy title="one membership per person per channel, and what a second one is told" test app=entity-unique-composite entity Channel { [Required, MaxLength(60)] string Name; } [Unique(Channel, Person, "They are already in this channel.")] entity Membership { [Required] Channel Channel; [Required] User Person; } [Principal] entity User { [Required, MaxLength(200)] string Email; } ``` This is the constraint a **join table** wants, and reaching for a `Membership.Any(…)` guard instead is the mistake the paragraph above describes: two requests can both read "not a member" before either writes, and only the index is enforced where that race is. Keep the guard as well if you want a quiet no-op on a double-click — but it is the convenience, not the rule. **Which field does the violation land on?** For a composite one, a field whose name is **the members joined with `", "`, in declaration order** — `Channel, Person` for the `Membership` above. Not either member on its own: the rule is about the combination, so what is refused is the combination, named as one thing. That is what a test aims at, and it is the one string you need: ```osy syntax title="aiming a test at the pair, not at either member" Assert.Violation("Channel, Person"); // the pair collided Assert.Violation("Channel, Person", "already in this channel"); // …and this is what it says ``` A single-member `[Unique]` is the ordinary case — the field is just the member. Either way the violation is raised by the **server**, at the save, because "is this taken?" is a question about other rows; see [[testing-ui#composite-unique]] for when a test may assert it. ⚠ A unique constraint is over a **table**, and one table holds a whole [inheritance](https://osysharp.com/reference/entity/inheritance/) hierarchy — so one declared on a base spans every type derived from it. That is usually what you want, and the compiler says so either way (it warns, naming every type covered). ### Write-once, decimal precision, and size bounds {#storage-shaping} Four constraints shape a value beyond "is it valid": - **`[Immutable]`** is a rule about *updates*, not presence: the member may be set when the row is created and then **never changed**. It is how you say "an order's placed-date is written once" — an attempt to update it is refused, from any code path. Pair it with `[Required]` when the value must also be present from the start. - **`[MinLength]`** is the floor to `[MaxLength]`'s ceiling: `[MinLength(n)]` requires text of at least `n` characters. - **`[Precision]`** pins how a `decimal` is stored: `[Precision(p, s)]` gives `p` total significant digits, `s` of them after the decimal point. `[Precision(10, 2)]` is the shape of money — up to eight digits before the point, two after. - **`[MaxBytes]`** bounds the stored size of a value in bytes: `[MaxBytes(n)]` caps a large field — a `Json` document or rich text — where the limit you care about is storage, not character count. ```osy title="immutable, precision, and a byte bound" test app=entity-constraints entity Invoice { [Required, Immutable] DateTime IssuedAt; // set once, at creation; never edited afterwards [Precision(10, 2)] decimal Amount; // money: 8 digits before the point, 2 after [MinLength(3), MaxLength(20)] string Number; // a bounded reference code [MaxBytes(1048576)] Json Payload; // at most 1 MB of stored JSON } ``` ### The rule spans several members — what then? {#beyond-one-member} A constraint speaks about **one member**. When the rule spans several — "shelf days must be under 30, but only for perishable items" — you want an [invariant](https://osysharp.com/reference/entity/invariants/). ## See also {#see-also} - [invariant](https://osysharp.com/reference/entity/invariants/) — rules that span several members of the row - [entity members](https://osysharp.com/reference/entity/properties/) — the members these constrain - [relations](https://osysharp.com/reference/entity/relations/) — `[Required]` on a reference --- # entity > Declares a persisted type — a table of rows the app stores, queries and secures. Every entity gets an Id and audit columns from the platform. Use a class instead when the value only lives in memory. ## Summary {#summary} An `entity` is a **persisted type**: a table of rows the app stores, queries and secures. It is the noun your application is about — `Order`, `Customer`, `Invoice`. Declaring one is enough to get a table, an identity, an audit trail and a query surface; you write the members, the platform provides the rest. If the value never needs to be stored — a computed shape, a DTO, the result of a calculation — use a [`class`](https://osysharp.com/reference/class/constructors/) instead. A class lives in memory and has no table. ## Signature {#signature} ```osy syntax entity { ; // data invariant ; // row-level rules security { … } // who may read and write it } ``` ## Description {#description} ### Which members do I get for free? {#provided} Every entity already has these. **Do not declare them** — a member of the same name is a compile error, because the platform is already providing one: | Member | Type | What it is | |---|---|---| | `Id` | `Guid` | the row's identity, assigned on create | | `CreatedAt` · `ModifiedAt` | `DateTime` | when the row was written | | `CreatedBy` · `ModifiedBy` | `Guid` | who wrote it | So an entity with two declared members has seven columns. You read them like any other member — `order.CreatedAt` works without you writing it. ### How do I create a row, and when is it saved? {#lifecycle} A row is created with `new`, exactly as in C#. It is persisted when the function commits — there is no `Save()` call to forget: ```osy title="an entity, and a function that makes one" test app=entity-declaration entity Customer { [Required] string Name; string Email; } void Register(string name, string email) { var c = new Customer { Name = name, Email = email }; // no Save() — the row is written when the function commits } ``` Reading is a query over the type itself — you name the entity and write LINQ against it: ```osy title="reading rows back" test app=entity-declaration int ActiveCustomers() { return Customer.Where(c => c.Email != null).ToList().Count; } Customer ByName(string name) { return Customer.Single(c => c.Name == name); // exactly one, or it faults } ``` The predicate is **compiled into the database query** — it is not a filter over rows you already fetched — so the shape of what you can ask for is worth knowing before you write your first loop: | I want to… | Read | |---|---| | filter, and pick one row or count them | [Where / Single / Count](https://osysharp.com/reference/query/where/) — `Where` · `Single` · `FirstOrDefault` · `Count` · `Any` | | run the query and get the rows | [ToList](https://osysharp.com/reference/query/tolist/) — `ToList`, and why you should call it once | | show page 3 of 40 | [Skip / Take (paging)](https://osysharp.com/reference/query/paging/) — `OrderBy` · `Skip` · `Take` | | drop duplicates | [Distinct](https://osysharp.com/reference/query/distinct/) — and why it does nothing on whole rows | | combine two result sets | [Union / Concat / Intersect / Except](https://osysharp.com/reference/query/set-operators/) — `Union` · `Concat` · `Intersect` · `Except` | | match against a list I have in hand | [Dynamic IN (list.Contains in a query)](https://osysharp.com/reference/query/dynamic-in/) — `list.Contains(x)` inside a query | | walk a parent's children | [relations](https://osysharp.com/reference/entity/relations/) — through the collection, **never** a filtered query | Reaching for a `foreach` to do work the query could have done is the most common way an application that was fast on a laptop becomes slow in production. ### Entity or class? {#entity-vs-class} | | `entity` | `class` | |---|---|---| | Stored in the database | **yes** — it has a table | no — in memory only | | Has an `Id` and audit columns | **yes**, from the platform | no; it has only what you declare | | Queryable (`Where`, `Single`, …) | **yes** | no | | Securable (`security { … }`) | **yes** | no — it holds no rows to protect | | Good for | the nouns you persist | DTOs, computed shapes, JSON bodies | The rule of thumb: **if you will ever query it, it is an entity.** ### Security: an entity nobody can read is the DEFAULT {#security} This is the part to read twice, because it is where the platform will surprise you — deliberately. **The posture is deny-all.** An entity that declares no `security { }` block is **denied to every user request**. Not "readable by signed-in users", not "readable by its owner" — denied. Your beautifully modelled `Order` entity is, until you say otherwise, an entity that no user of your application can read, write or count. That is the correct default, and it is chosen on purpose. The failure mode of forgetting a rule is *"nobody can do it"* — which someone reports within the minute — rather than *"everybody can"*, which nobody reports until it is somebody else's headline. A door that fails shut is a door you can trust. So **declaring who may read an entity is part of declaring the entity.** It is not a hardening pass you schedule for later; there is no working application before you have done it. ```osy title="an entity only its owner can read" test app=entity-declaration [Principal] entity User { [Required] string Name; } entity Note { User Owner; string Body; security { allow read where Owner == user; } } ``` Note what the block does **not** contain: there is no `default deny`. Everything is denied already, so a `security { }` block is a list of **grants** — you only ever write what is allowed. (To lock an entity completely, write no block at all.) Two rules, two different questions, and the distinction is the whole model: - **`where`** filters by the **row** — *the owner sees their own notes*. - **`when`** gates by the **principal** — *staff see every note*. And note what you cannot do: a bare `allow read;` is a **compile error** on an app that has a principal. The platform makes you say *who* may read — `allow read when IsAuthenticated;`, or `IsAuthenticated || IsAnonymous` if you really do mean the whole internet. Opening a door is allowed; opening one by accident is not. Read these three, in this order, before you ship anything: 1. [secure by default (deny-all)](https://osysharp.com/reference/security/secure-by-default/) — the deny-all posture, and what it does and does not cover 2. [security { }](https://osysharp.com/reference/security/entity-security/) — the `security { }` block in full: `where`, `when`, and named `policy` predicates 3. [runas](https://osysharp.com/reference/testing/runas/) — because **a security rule you have not tested is a rule you only believe you wrote** That last one is not a flourish. Security is the one area where the code compiling, the tests passing and the feature working tell you nothing about whether it is correct — the only way to know that Bob cannot read Alice's note is to become Bob and try. ## See also {#see-also} - [entity members](https://osysharp.com/reference/entity/properties/) — the member types an entity can hold - [relations](https://osysharp.com/reference/entity/relations/) — pointing one entity at another, and reading the children back - [constraints](https://osysharp.com/reference/entity/constraints/) — `[Required]`, `[Unique]`, `[MaxLength]`, ranges and patterns - [invariant](https://osysharp.com/reference/entity/invariants/) — row-level rules enforced when the row is written - [constructor](https://osysharp.com/reference/class/constructors/) — the in-memory counterpart, for values you never store - [secure by default (deny-all)](https://osysharp.com/reference/security/secure-by-default/) — the deny-all posture: what an entity permits before you say anything - [security { }](https://osysharp.com/reference/security/entity-security/) — the `security { }` block in full - [Where / Single / Count](https://osysharp.com/reference/query/where/) — querying the rows, and the rest of the LINQ surface - [runas](https://osysharp.com/reference/testing/runas/) — proving your rules deny the people they should --- # entity Sub : Base > Derives one entity from another. The subtype is its own type with its own name, its own security and its own workflows, and it carries every member of its base. Both store their rows in one table. ## Summary {#summary} `entity RushOrder : Order` derives one entity from another, with C#'s colon and C#'s meaning. The subtype is its **own type** — its own name, its own security rules, its own workflows — and it carries **every member of its base** plus whatever it adds. Both types store their rows in **one table**. Those two facts are the whole feature, and everything below is a consequence of one or the other. ## Signature {#signature} ```osy syntax entity : { ; // members of its OWN, on top of everything Base declares invariant ; // its own checks; Base's still apply security { … } // its OWN rules — nothing is inherited here } ``` ## Description {#description} ### What a subtype is {#what} A subtype is a **distinct type**. It has its own name, and everything the platform keys on a type keys on it separately: its security rules are its own, a workflow that tracks it tracks only it, and a row of it reads back as itself. It is also **complete**. You do not reach through a base to get at inherited members — `RushOrder` simply *has* `Reference`, in a query, in a UI binding, in a function: ```osy title="a base, a subtype, and both of their members" test app=entity-inheritance entity Order { [Required, MaxLength(120)] string Reference; int Quantity; } entity RushOrder : Order { [Required, MaxLength(60)] string Courier; } void Ship() { // `Reference` and `Quantity` come from Order; `Courier` is RushOrder's own. No difference at the use site. var rush = new RushOrder { Reference = "R-1001", Quantity = 2, Courier = "DHL" }; } ``` ### Where are a subtype's rows stored? {#storage} A subtype's rows live in its **base's table**, alongside the base's own. A hidden platform-written column records which type each row is. This is not an implementation detail you can ignore, because it is what makes the useful things possible: a reference typed `Order` can hold a `RushOrder`, a parent-child tree can span types, and there is **one id space**, so nothing has to ask "which table is this id in". It is also why a subtype may not redeclare a base member — see [One column, so no redeclaring](#one-column) — and why `[Unique]` reaches further than you might expect — see [Unique spans the hierarchy](#unique). One consequence is worth knowing if you ever look at the table directly: **a member only a subtype declares is optional in the database**, because rows of every other type genuinely have no value for it. `[Required]` is still enforced — for that type, on every write — but the column itself holds NULL for everyone else, rather than a fabricated blank. ### A subtype goes wherever its base is wanted {#upcast} A `SignedContract` **is** a `Document`, so it goes anywhere a `Document` is expected — a member, a function argument — with no cast, exactly as in C#. This is what one table and one id space buy: a single reference column holds any kind, and nothing at the far end knows the hierarchy exists. ```osy title="one FK, every kind of document" test app=entity-inheritance-upcast entity Document { [Required, MaxLength(200)] string Title; } entity Contract : Document { [Required, MaxLength(80)] string Counterparty; } entity Note { [Required] Document Document; // typed as the ROOT… [Required, MaxLength(400)] string Body; } void Annotate() { var c = new Contract { Title = "Supply", Counterparty = "Acme" }; new Note { Document = c, Body = "countersigned" }; // …and a Contract goes straight in } ``` "Anywhere a `Document` is expected" includes the places where two values have to agree on one type — a `?:`, a `switch` expression, a `??` fallback. The result is the **base** of the two, so `Document d = rush ? contract : doc;` is the ordinary way to pick between them. Two SIBLINGS — a `Contract` and an `Invoice` — have no common type to *infer*, so they take the type they are written INTO: `Document d = rush ? contract : invoice;` is fine, while `var d = …` has nothing to take and says so. The other direction — treating a `Document` you are holding as a `Contract` — can fail at run time, so you state it: [test the row](#narrowing) with `is`, or narrow a whole set with `OfType()`. ### Reading a type returns everything below it {#reads} `Order.Where(…)` returns rush orders too, because a `RushOrder` **is** an `Order` — the same thing a `List` means in C#. **Narrowing is what you state:** `RushOrder.Where(…)` returns rush orders and whatever derives from them, and never a plain `Order`. `Count()`, a collection you navigate to and a tree you walk all read the same way. Each row that comes back is governed by [its own type's rules](#security), never by the type you asked through — so a base read can return fewer rows than the table holds, and that is the rules working rather than a missing row. ```osy title="a base read returns every kind below it" test app=entity-inheritance int AllOrders() { // The rush orders too — they are orders. return Order.Where(o => o.Quantity > 0).ToList().Count; } int RushOnly() { return RushOrder.Where(o => o.Quantity > 0).ToList().Count; } ``` ### How do I get back just one kind? — `is` and `OfType` {#narrowing} A base read hands you every kind. **`is` tests one row; `OfType()` narrows a whole set** — and both are polymorphic downward, because a `SignedContract` **is** a `Contract`. `x is Contract` is a plain condition: it works in a query, where it becomes a check the database does without reading any rows, and in ordinary code. `is not Contract` is its negation. ```osy title="test one row, narrow one set" test app=entity-inheritance-narrow entity Document { [Required, MaxLength(200)] string Title; } entity Contract : Document { [Required, MaxLength(80)] string Counterparty; } entity SignedContract : Contract { [Required, MaxLength(60)] string Signatory; } // In a query — the database answers it; nothing is loaded to decide. int ContractCount() { return Document.Where(d => d is Contract).ToList().Count; } // `OfType()` gives you a set of that type, so its own members are readable. string Counterparties() { var all = ""; foreach (var c in Document.OfType().ToList()) { all = all + c.Counterparty + ";"; } return all; } ``` Both count the `SignedContract` too. To ask for *only* the leaf, name it: `Document.OfType()`. #### Why can't I read the subtype's members after `is`? {#narrowing-pattern} `is` on its own answers a question; it does not change what you may read. `d is Contract` tells you the row is a contract, and `d` is still a `Document`, so `d.Counterparty` does not compile. Give the test a **name** and it does: ```osy title="one list, one loop, rendered per kind" test app=entity-inheritance-narrow2 entity Document { [Required, MaxLength(200)] string Title; } entity Contract : Document { [Required, MaxLength(80)] string Counterparty; } entity Memo : Document { } string Render() { var lines = ""; foreach (var d in Document.OrderBy(x => x.Title).ToList()) { if (d is Contract c) { lines = lines + d.Title + " with " + c.Counterparty + "\n"; // `c` is the same row, as a Contract } else { lines = lines + d.Title + "\n"; } } return lines; } ``` `c` is the row you tested — nothing is copied — and it exists **inside the `if` only**. That is deliberate: outside the branch the test may not have held, and a name that reads a row as a kind it is not would be worse than no name. For the same reason these are refused, each with a sentence saying what to write instead: | Written | Why | |---|---| | `is not Contract c` | the test *failing* says nothing about what `c` would be | | `var b = d is Contract c;` | `c` belongs to a branch, and there is no branch here — use `is Contract` to get the answer | | `(Contract)d` | a written downcast must fail at run time when the row is not one, and that check is not built | ### Security is never inherited {#security} A subtype declares its **own** `security { }` block, and inherits nothing from its base. That is deliberate, and it is the safe direction. An entity with no policy grants nothing, so a subtype whose author has not yet thought about who may read it returns **no rows** — rather than silently receiving whatever grant its base happened to have. A row is always governed by the rules of **its actual type**, never by the type you reached it through. ```osy title="the subtype states its own rules" test app=entity-inheritance-security [Role] enum AppRole { Authenticator, Member } [Principal] entity User { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } entity Document { [Required, MaxLength(200)] string Title; security { allow create, read when IsAuthenticated; } // any signed-in user sees any Document } entity Contract : Document { [Required, MaxLength(80)] string Counterparty; // Its OWN, and narrower. Nothing of Document's grant carries over — had this block been left out entirely, a // Contract would be readable by nobody, which is the direction you want to be wrong in. security { allow create, read where CreatedBy == user.Id; } } ``` ### What IS inherited {#inherited} | Declaration | Inherited? | Why | |---|---|---| | members, and their attributes (`[Required]`, `[MaxLength]`, `[Searchable]`, …) | **yes** | they travel with the member, which the subtype has | | `semantic => …` (the search card) | **yes**, and a subtype may declare its own to override | it is a *description*, and a subtype that adds nothing genuinely describes itself the same way | | depth | **unlimited** — `SignedContract : Contract : Document` carries every member of both levels above it | | | `invariant` | **yes**, and the subtype's own add to them | it is a *constraint*, and constraints only accumulate — a subtype cannot drop one | | `security { }` | **no** — always its own | it is an *authority* question, where silence must mean no | Description defaults to inheritance; authority defaults to denial. ### Can I redeclare a base's member on a subtype? {#one-column} Because both types share a table, a member declared on both is not a shadowed member — it is **one column claimed by two declarations**. C# lets you shadow with `new`; a table cannot, so there is no spelling for it and the compiler asks you to delete one: ```osy title="✗ a subtype redeclaring a base member — one column, two claims" syntax entity Order { [Required] string Reference; } entity RushOrder : Order { [Required] string Reference; // ✗ 'RushOrder.Reference' redeclares 'Order.Reference' } ``` The realistic way to hit this is not a typo — it is a base gaining a member later that a subtype already used. The error names both declarations so you can see which one you meant. **Two SIBLINGS may share a member name, as long as they agree about it.** `Rush.Note` and `Standby.Note` do not collide with each other the way a subtype collides with its base — they are different rows — so one shared column serves both: ```osy title="siblings sharing a name, agreeing about it" test app=entity-inheritance-siblings entity Ticket { [Required, MaxLength(200)] string Title; } entity Bug : Ticket { [MaxLength(80)] string Area; } entity Feature : Ticket { [MaxLength(80)] string Area; } // same column, same meaning — fine ``` What is refused is the two **disagreeing**, because there is only one column and only one of them can win: ```osy title="✗ siblings disagreeing about the shared column" syntax entity Bug : Ticket { [MaxLength(80)] string Area; } entity Feature : Ticket { int Area; } // ✗ one column, declared as `string` by one type and `int` by the other ``` ### `[Unique]` spans the hierarchy {#unique} A unique constraint is over a **table**, and one table holds every type in the hierarchy. So `[Unique]` on a base is unique across the base *and every type derived from it*: ```osy title="one code, across every kind of order" test app=entity-inheritance-unique entity Order { [Required, Unique, MaxLength(40)] string Code; // no two Orders share a Code… } entity RushOrder : Order { // …and a RushOrder is an Order, so it is in the same space [Required, MaxLength(60)] string Courier; } ``` An `Order` with `Code = "A-1"` and a `RushOrder` with `Code = "A-1"` is refused. That is usually exactly what you want — one id space is much of the point of sharing a table — but it is impossible to read off the declaration, and the other reading ("unique among Orders") is equally plausible. **So the compiler warns**, naming every type the constraint covers: > `'Order.Code' is unique across EVERY type stored in 'Order's table — Order, RushOrder — not just 'Order'.` It is a warning rather than an error because the behaviour is correct; what was missing is that you were told. There is no per-type spelling: if hierarchy-wide is not what you meant, the member belongs on one type rather than on a shared one. The same warning appears for a composite `[Unique(A, B)]` and for a `[Unique]` a subtype declares. ### What happens to the rows if I remove a subtype? {#removing} Deleting a subtype from your source means the same thing as deleting any other entity: **its rows go, and nobody else's do.** It does not drop the shared table, the base and its siblings are untouched, and the columns that only the removed type declared go with it. Like every other drop it is gated — a plain recompile reports it and keeps the type, and removing it for real needs `--prune` in development or an acknowledged migration in production. Deleting a **base** while something still derives from it is a compile error: the subtype's `: Base` names a type your application no longer declares. Remove the subtype in the same change, or keep the base. ### What is refused {#refused} | Written | Refused because | |---|---| | a `sealed` base | the type said no type may derive from it — see [sealed](https://osysharp.com/reference/entity/sealed/) | | two bases (`: A, B`) | Osy# has no interfaces, so a second name could only be a second base, and a row has one type | | `class X : Y` | a class is an in-memory value, not a table; give it a field of the other type and compose | | an entity deriving from a class, or the reverse | different kinds — one is a table, one is not | | `extends` / `implements` | other languages' spellings; Osy# keeps C#'s colon, one spelling per concept | | two siblings declaring one member DIFFERENTLY | one column, and only one of the two declarations can win | | a written DOWNCAST (`(Contract)d`) | it must fail at run time when the row is not one, and that check is not built — [narrow instead](#narrowing) with `is` or `OfType()`, which cannot fail | | a member other than `security { }` on a subtype of a **platform** type | it shares a table the platform owns and writes — see [below](#platform-types) | ### Deriving from a platform type {#platform-types} A type a capability brings in may be derived from when it is not `sealed` — today that is `AgentTask`, so an app can give its own kind of agent work its own type, its own rules and its own process. **A subtype of a platform type declares `security { }` and nothing else.** It shares a table the platform owns and writes, so adding a column to it would reshape platform storage — the same rule a `partial entity` over a platform type already follows. Your own types are unrestricted: a subtype of a type *you* declare adds whatever it likes. ```osy title="an app's own kind of task, with its own loop" test app=entity-inheritance-platform using Osysharp.Agents; [Principal] entity Person { [Required, MaxLength(255)] string Email; security { allow read when IsAuthenticated; } } // A distinct type sharing AgentTask's table — no new columns anywhere. entity PersonalTask : AgentTask { security { allow read when IsAuthenticated; } } workflow PersonalTaskProcessor { Tracks = PersonalTask.Status; Initial = Running; state Running { } state Waiting { } terminal success Completed { } terminal error Failed { } } app.Agent = new AgentConfig { Loop = PersonalTaskProcessor }; ``` The task rows an agent opens under that loop **are** `PersonalTask`s: a task's type is the type its loop tracks. A plain agent with no loop, or one whose loop tracks `AgentTask` itself, still gets an `AgentTask`. Rows of a platform type stay platform-written through the subtype — the new name grants no ability to create, change or delete one that the base did not. Its fields, references and child collections all come through: `personalTask.Children` reads the same relation `AgentTask.Children` does, because it IS that relation — there is one table, one foreign key, and one relation over it, whichever type you reach them through. ### Workflows bind one type {#workflows} `Tracks = RushOrder.Status` binds `RushOrder` and nothing else — a workflow over a base does **not** cover its subtypes. That is what keeps *one state machine per column* true: a base's run and a subtype's run would otherwise both drive one `Status` value on one row. It is also what makes inheritance the natural way to give two kinds of thing two different processes: give each its own type, and each type its own workflow. ## Examples {#examples} ```osy title="two kinds of task, two processes" test app=entity-inheritance-tasks enum TaskState { Open, Doing, Done } entity WorkItem { [Required, MaxLength(200)] string Title; TaskState State = TaskState.Open; } // Its own type, so its own rules and its own process — and no new columns. entity UrgentItem : WorkItem { [Required] DateTime DueBy; } ``` ## See also {#see-also} - [sealed](https://osysharp.com/reference/entity/sealed/) — how a type says no one may derive from it - [entity](https://osysharp.com/reference/entity/declaration/) — what an `entity` is, and what the platform provides for free - [security { }](https://osysharp.com/reference/security/entity-security/) — the `security { }` block a subtype must write for itself - [invariant](https://osysharp.com/reference/entity/invariants/) — the row-level checks a subtype accumulates from its base - [relations](https://osysharp.com/reference/entity/relations/) — a reference typed as a base holds any of its subtypes - **`demo/entity-inheritance`** — the runnable demo: four kinds of document in one table, three levels deep, with per-type security you can see by signing in as three different people (`osy docs sample` does not ship it; it lives in the repo's `demo/` tree) --- # entity members > The typed members an entity holds — text, numbers, dates, booleans, Guids, enums and references. A member's type spelling carries its nullability: a bare `string`, enum, `DateTime` or `Guid` is REQUIRED, a bare value type reads its zero, a reference is optional, and `?` makes any member optional. See [[types-optional-and-required]]. ## Summary {#summary} An entity's members are declared C#-style — `decimal Total;` — one per line, with optional attributes in front. Each becomes a column. Whether a member is **required or optional is carried by its type spelling**, not a separate keyword: a bare `string`, enum, `DateTime` or `Guid` is **required**, a bare value type (`int`, `bool`, `decimal`) reads its zero, a **reference is optional**, and the `?` suffix makes any member optional. The full model — and *when* a required member is checked — is [Optional and required members](https://osysharp.com/reference/types/optional-and-required/); the essentials are below. ## Signature {#signature} ```osy syntax entity { ? ; } ``` ## Description {#description} ### Which types may a member hold? {#types} **This table is the whole storable set** — [Every type, in one list](https://osysharp.com/reference/types/vocabulary/) is the same list with the non-storable types (the collections, `Action`/`Func`, the component-parameter wrappers) beside it. If a type is not here and you did not declare it yourself, an entity cannot hold it. | Type | Holds | Notes | |---|---|---| | `string` | text | give it a `[MaxLength(n)]` — see below | | `int` · `long` | whole numbers | `long` for ids and counters past 2³¹ — [long](https://osysharp.com/reference/types/long/) | | `double` | measurements | a binary float — **never money** | | `decimal` | money and exact quantities | **use this for money**, never a floating type — [decimal](https://osysharp.com/reference/types/decimal/) | | `bool` | true / false | | | `DateTime` | a point in time | stored UTC — [DateTime](https://osysharp.com/reference/types/datetime/) | | `DateOnly` | a calendar date, no time | a SQL `date` — [DateOnly and TimeOnly](https://osysharp.com/reference/types/date-and-time/) | | `TimeOnly` | a time of day, no date | a SQL `time` — [DateOnly and TimeOnly](https://osysharp.com/reference/types/date-and-time/) | | `TimeSpan` | a duration | [TimeSpan (durations)](https://osysharp.com/reference/types/timespan/) | | `Guid` | an identifier | | | `Json` | an arbitrary JSON document | for genuinely open-shaped data — [Json](https://osysharp.com/reference/types/json/) | | `Markdown` | a section-addressable markdown document | text plus a rendering contract — [Markdown](https://osysharp.com/reference/types/markdown/) | | `RichText` | formatted prose | a rich-text document | | `Vector` | an embedding, for similarity search | `[MaxLength(n)]` sets the dimensions — [[Searchable]](https://osysharp.com/reference/memory/searchable/) | | `Zone` | an IANA time-zone token (`Europe/Stockholm`) | [Time zones — the Zone type and its operations](https://osysharp.com/reference/stdlib/zones/) | | `Culture` | a BCP-47 culture token (`sv-SE`) | [Culture formatting — ToString(format, culture)](https://osysharp.com/reference/stdlib/culture-formatting/) | | `byte[]` | binary | the one array form that is a scalar, not a collection | | an `enum` you declared | a fixed set of values | see [enum](https://osysharp.com/reference/enum/declaration/) | | another `entity` | a reference to one row | see [relations](https://osysharp.com/reference/entity/relations/) | | `[]` | the children pointing back at this row | see [relations](https://osysharp.com/reference/entity/relations/) | ```osy title="the scalar types" test app=entity-properties entity Invoice { [MaxLength(40)] string Number; decimal Total; // money is ALWAYS decimal int LineCount; bool Paid; DateTime IssuedAt; Guid ExternalRef; } ``` The date/time trio and `Json` are **ordinary columns like any other** — there is no conversion to write and no `DateTime` to fall back on. Reach for `DateOnly` when the time of day is not a fact about the row (a birthday, an invoice date, the day a slot is booked for), and `TimeOnly` when the date is not (opening hours, a daily cutoff): ```osy title="dates without times, times without dates, and open-shaped data" test app=entity-properties entity Appointment { DateOnly Day; // a calendar date — no time of day to get wrong TimeOnly StartsAt; // a time of day — no date attached TimeSpan Runs; // how long it lasts Json Extras; // genuinely open-shaped data, stored as a document } DateOnly WhenIsIt(Appointment a) { return a.Day; } // and it reads back as itself ``` **A member may be named for its own type**, exactly as `Color Color;` is in C# — and it is the natural spelling for the commonest fields (`Room Room`, `Status Status`, `Type Type`). No prefix, no suffix, no second word: ```osy title="a member named for its own type — C#'s `Color Color`" test app=entity-properties enum Room { Kitchen, Bathroom, Bedroom } entity Kiln { [Required, MaxLength(80)] string Name; [Required] Room Room; // the member and its type share a name — legal, and the name to use } Room WhereIsIt(Kiln p) { return p.Room; } // and it reads back with no ceremony ``` ### Is this member required, or may it be null? {#optional} Whether a member is required is decided by **how you spell its type** — there is no separate keyword. What a *bare* (non-`?`) member means depends on whether its type has a natural zero (full treatment: [Optional and required members](https://osysharp.com/reference/types/optional-and-required/)): - A **bare `string`, enum, `DateTime`/`DateOnly`/`TimeOnly`, `Guid` or `Json`** — a type with **no honest zero** — is **required**: the platform invents no value for it, so you must supply one. (An enum is *not* silently defaulted to its first member — reordering the members would change the stored default — so a bare enum is required too.) - A **bare value-type scalar** — `int`, `long`, `bool`, `decimal`, `TimeSpan` — reads its **zero** (`0`, `false`, `0m`) when unset, exactly as a C# field does. It is never null; declare it `int?` for a real "unset". (Because it is never null, comparing one to `null` — `priority == null` — is a compile error that points you at the `?` form.) - A **bare entity reference is optional** (reads back `null`) — the everyday shape is *create the row, then pick the related record* — and you write `[Required]` to demand one. - The **`?` suffix** makes any member optional; it reads back `null` when nobody set it. **When is a required member checked?** An entity is a **draft until commit**, so `new Ticket {}` compiles — you seed an empty draft, bind each field to a form input, and the required members are validated **at commit**, naming any that are still unset. (A `class` has no commit step, so its required members are checked at `new` instead — see [class properties](https://osysharp.com/reference/class/properties/).) This is what makes the everyday create-form work. ```osy title="required by spelling; optional with ?" test app=entity-properties entity Contact { string Name; // REQUIRED — a bare string has no honest zero (checked at commit) string? Phone; // optional — a contact without a phone is fine; reads back null DateTime? LastSpokeAt; // `?` is not a string thing: ANY type takes it, value types included int? Doorstep; // `int?` is genuinely absent, which is what `0` could never say } string PhoneOrDash(Contact c) { return c.Phone ?? "—"; // null-coalescing on the optional field, exactly as in C# } ``` ⚑ **EVERY C# NULLABLE TYPE IS SUPPORTED.** `?` is not a string affordance — it is the C# rule, and it holds for value types and reference types alike: `DateTime?`, `int?`, `decimal?`, `bool?`, `Guid?`, `TimeOnly?`, an enum, your own `class`. There is no list to check against, which is why this page states the rule rather than enumerating one. ⚠ **It is written down because the shape is usually only ever SHOWN on a string**, and a reader who has seen `string?` and nothing else has to guess. The guess costs a field: measured 2026-09-01, a model reasoning aloud — *"`DateTime?` — is nullable DateTime supported? The docs mention `string?` for nullable"* — and it dropped the field rather than find out. A bare **reference** is the exception — optional by default, so write `[Required]` to demand one: `[Required] Customer Reporter;`. See [relations](https://osysharp.com/reference/entity/relations/) and [Optional and required members](https://osysharp.com/reference/types/optional-and-required/). ### How do I give a member a default value? {#defaults} A member may declare a default, which applies when the row is created without one — `= true`, `= 0m`, or an enum member. It is the honest way to say *"this is what a new one looks like"*, instead of remembering to set it at every creation site: ```osy title="what a new row looks like" test app=entity-properties enum AccountStatus { Active, Suspended, Closed } entity Account { [Required, MaxLength(200)] string Name; bool IsActive = true; // a new account is active AccountStatus Status = AccountStatus.Active; // …and its status says so decimal Balance = 0m; [Required] string ApiKey = Security.RandomId(32); // a fresh unguessable key per account DateTime CreatedFor = DateTime.UtcNow.AddDays(30); // …and a computed date, evaluated at creation } void Open(string name) { var a = new Account { Name = name }; // IsActive is true, Status is Active, Balance is 0 — none of them written here; // ApiKey is a fresh 32-char id and CreatedFor is 30 days out — each EVALUATED for this new row } ``` A default is not limited to a constant. It can be **any expression** — a call like `Security.RandomId(32)`, a computed value like `DateTime.UtcNow.AddDays(30)`, arithmetic — and it is **evaluated afresh for each row at creation**, exactly like a C# field initializer. So two accounts opened in the same breath get two *different* `ApiKey`s; the expression runs per row, not once. (A constant/enum default behaves the same as always.) Reach for a default whenever "unset" and "the normal value" are the same thing. It removes a whole class of bug: the creation site somebody added last week that forgot to set `IsActive`, and the row that has been invisible ever since. ### Text needs a length {#maxlength} `string` with no `[MaxLength]` is unbounded. That is fine for a body of prose and wrong for a code, a name or a status — give those a length, and the database enforces it: ```osy title="bounded and unbounded text" test app=entity-properties entity Article { [MaxLength(200)] string Title; // bounded — a title has a sane maximum string Body; // unbounded — prose } ``` ### Money is `decimal` {#money} There is no `float` or `double` member type, and that is on purpose: binary floating point cannot represent `0.10`, so totals drift by fractions of a cent and eventually a customer notices. `decimal` is exact. ### How do I index a member, or rename its column? {#storage-attributes} A handful of attributes shape how a member is *stored* rather than what it may hold. Most rows never need them: - **`[Index]`** asks the database to index the member, so queries that filter or sort by it stay fast as the table grows. Put it on the members you actually query by. - **`[ExternalName]`** overrides the database column name when it must differ from the member — `[ExternalName("col")]` maps onto a pre-existing or externally-owned schema. - **`[Virtual]`** marks a member **in-memory only**: it is never persisted, for a value you compute and carry but do not store. - **`[Id]`** marks a member as the entity's primary key. Every entity already has an automatic `Id`, so you only reach for this to supply your own key instead of the default. - **`[DynamicType]`** lets a member's type be resolved at runtime rather than fixed at declaration — an advanced escape hatch for genuinely polymorphic storage. - **`[Mentions]`** declares the entities a rich-text member may `@`-mention, so an editor can offer and resolve them. ```osy title="indexing and an external column name" test app=entity-properties entity LegacyCustomer { [Required, Index] string Status; // queried often → indexed [ExternalName("cust_ref")] string Reference; // the column is named cust_ref in the database [Virtual] int ScoreThisSession; // computed and carried, never stored } ``` ## See also {#see-also} - [entity](https://osysharp.com/reference/entity/declaration/) — the type these members live in - [constraints](https://osysharp.com/reference/entity/constraints/) — `[Required]`, `[Unique]`, `[MaxLength]`, `[Min]`/`[Max]`, `[Pattern]` - [relations](https://osysharp.com/reference/entity/relations/) — members that point at another entity - [enum](https://osysharp.com/reference/enum/declaration/) — a member with a fixed set of values --- # invariant > A row-level rule spanning several members, checked when the row is written. Use it when a constraint on one member is not enough — a balance that may not go negative, or a rule that only applies to some rows. ## Summary {#summary} An `invariant` is a rule about **the whole row**, enforced when the row is written. A [constraint](https://osysharp.com/reference/entity/constraints/) speaks about one member (`[Max(5)] int Priority`); an invariant speaks about the relationship between members — and can be conditional, so it applies only to the rows it should. ## Signature {#signature} ```osy syntax entity { invariant ; // always holds invariant when ; // holds only for rows where is true invariant when message ""; // …and say why, when it fails } ``` ## Description {#description} ### How do I write a rule over the whole row? {#always} The condition is written over the row's own members, and must be true when the row is written: ```osy title="a balance that may never go negative" test app=entity-invariants entity Account { [Required] string Holder; decimal Balance; invariant Balance >= 0; } ``` Any code path that would leave `Balance` negative — a withdrawal, an import, an adjustment — fails at commit. You do not have to remember to check it, and neither does the next person. ### A rule that applies to some rows {#when} `when` guards the invariant. The rule is only checked for rows where the guard is true, so one entity can hold several kinds of row without the rules of one contaminating the others: ```osy title="a rule that only applies to perishable goods" test app=entity-invariants entity Product { [Required] string Name; bool IsPerishable; int ShelfDays; invariant ShelfDays <= 30 when IsPerishable message "Perishable items can have at most 30 shelf days."; } ``` A tin of beans with `ShelfDays = 400` is fine — the guard is false, so the rule never fires. Milk with the same value is rejected, and the person who tried gets the sentence you wrote rather than a constraint name. ### How do I say why it failed? — `message` {#message} `message` is the explanation a human sees. Without it they get a rule that says `ShelfDays <= 30`, which tells them what was violated but not what to do. Write the message as though you are talking to the person who hit it — because you are. ### What an invariant can see {#scope} The row it is on. An invariant reads the members of its own entity; it does not run a query and it does not reach across into other rows. That is what keeps it cheap enough to check on every write. ## See also {#see-also} - [constraints](https://osysharp.com/reference/entity/constraints/) — the single-member rules (`[Required]`, `[Unique]`, `[Min]`/`[Max]`, `[Pattern]`) - [entity members](https://osysharp.com/reference/entity/properties/) — the members an invariant reads - [entity](https://osysharp.com/reference/entity/declaration/) — the entity an invariant guards --- # relations > One entity points at another by declaring it as a member — that is the foreign key. The parent reads its children back through a collection member marked with ForeignKey. Never query children with a filter; go through the collection. ## Summary {#summary} A relation is two halves of one idea. The **child** points up by declaring the parent as a member — `Order Order;` — which is the foreign key. The **parent** reads down through a collection member — `[ForeignKey(Order)] LineItem[] LineItems;`. Declare both, and you can walk the graph in either direction. ## Signature {#signature} ```osy syntax entity { [Required] ; // the FK — one row of the parent } entity { [ForeignKey()] [] ; // the children pointing back at this row } ``` ## Description {#description} ### How do I declare both sides of a relation? {#two-halves} The child's member IS the foreign key — there is no `OrderId` to declare and keep in step. You assign a row, not an id, and you read a row back. The parent's collection member carries the **`[ForeignKey]`** attribute, naming the relation it reads down — `[ForeignKey(Order)]` on the `Order`'s `Lines`: ```osy title="an order and its lines" test app=entity-relations entity Order { [Required] string Code; decimal Total; [ForeignKey(Order)] LineItem[] Lines; // read down: this order's lines } entity LineItem { [Required] Order Order; // point up: the order this line belongs to [MaxLength(200)] string Product; decimal Amount; } void AddLine(string orderCode, string product, decimal amount) { var order = Order.Single(o => o.Code == orderCode); var line = new LineItem { Order = order, Product = product, Amount = amount }; // ^^^^^^^^^^^^^ assign the ROW, not an id } ``` `[Required]` on the child's parent member means an orphan is impossible: a `LineItem` with no `Order` is a violation at commit, not a row nobody notices for six months. ### Read children through the collection, never a filter {#never-query-children} This is the one rule people get wrong. To get an order's lines, go through the collection: ```osy title="reading a parent's children" test app=entity-relations decimal OrderTotal(string code) { var order = Order.Single(o => o.Code == code); var total = 0m; foreach (var line in order.Lines) { // the collection — connected to the order you already loaded total += line.Amount; } return total; } ``` Do **not** write a standalone query filtered on the foreign key to fetch children. It looks equivalent and is not: the collection is part of the object graph you already have, so it is loaded once and reused, while a separate query is disconnected from the parent and re-runs every time you touch it. The collection is the connected path; a filtered query is a second, unrelated result set that happens to contain the same rows. ### How do I let a reference be unset? {#optional} Leave off `[Required]` and the reference may be null — a `Ticket` that nobody is assigned to yet: ```osy title="an optional reference" test app=entity-relations entity Person { [Required] string Name; } entity Ticket { [Required] string Title; Person Assignee; // may be null — an unassigned ticket is a real state } string AssigneeName(Ticket t) { return t.Assignee?.Name ?? "unassigned"; // null-safe, exactly as in C# } ``` ### What `[Required]` decides about deleting {#required-and-delete} A required reference says the child **cannot exist without its parent**, and the platform takes that literally: deleting the parent deletes those children with it. An optional reference is the other answer — deleting the parent leaves the child and clears its reference. ```osy syntax entity Tag { [Required] Note Note; // deleting the Note deletes this Tag } entity Draft { Note Note; // deleting the Note leaves this Draft, with Note cleared } ``` ⚠ **This is where the decision is made, so it is worth making deliberately.** A cascade removes the children **without asking whether the caller could have deleted them on their own** — someone allowed to delete a `Note` can delete its `Tag`s by deleting the note, even where your rules never grant them `delete` on `Tag`. That is the declaration doing what it says rather than a gap in it: the alternative would be a legal model that fails at run time, with nothing you could write to fix it. So if a child's removal should be governed separately from its parent's, do not make its reference required — model it as optional and delete it explicitly. ## See also {#see-also} - [entity](https://osysharp.com/reference/entity/declaration/) — the entities a relation joins - [constraints](https://osysharp.com/reference/entity/constraints/) — `[Required]` on a reference is what forbids an orphan - [Where / Single / Count](https://osysharp.com/reference/query/where/) — querying the entities themselves --- # sealed > Declares that no type may derive from this entity. A type is open unless it says otherwise, exactly as in C#. Sealing says nothing about who may read or write the type. ## Summary {#summary} `sealed entity Invoice { … }` declares that **no type may derive from this one**. It is C#'s keyword with C#'s default: a type is **open unless sealed**. Sealing is a decision a type makes **about itself**. It has nothing to do with access — a sealed entity's rows are read and written exactly as any other's, governed by its `security { }` block. ## Signature {#signature} ```osy syntax sealed entity { } ``` ## Description {#description} ### What does `sealed` do? {#what} An attempt to derive from a sealed type is a compile error, naming the sealed type: ```osy syntax sealed entity Invoice { [Required] string Number; } entity CreditNote : Invoice { … } // ✗ 'Invoice' is `sealed`, so no type may derive from it ``` Seal a type when its shape and its rules are the whole story and a subtype would only blur them — a ledger entry, an audit row, a settled document. Leave it open when deriving is a use you intend to support. ### What sealing is NOT — access control, `partial`, `class` {#orthogonal} - **Sealing is not access control.** It does not restrict reading or writing; that is the [`security { }`](https://osysharp.com/reference/security/entity-security/) block, and a sealed entity takes one exactly as any other does. - **Sealing is compatible with `partial`.** `partial entity X { security { … } }` states more about *this* type; sealing refuses a *new* type. C# treats them as orthogonal for the same reason. (`sealed` **on** a `partial` is refused, though — a partial does not declare the type, so it cannot decide what may derive from it.) - **A `class` is sealed already**, by fact rather than by declaration: nothing can derive from an in-memory value type in Osy#, so writing the word there would say nothing and is refused. ### The platform seals its own types {#platform} Every type the platform ships is sealed, with deliberate, reviewed exceptions for the ones you are meant to extend. So if a platform type takes a `: Base` clause, that is a commitment rather than an oversight. ## Examples {#examples} ```osy title="a settled document, and an open one" test app=entity-sealed // Nothing derives from a posted ledger entry — its shape and its rules ARE the record. sealed entity LedgerEntry { [Required, MaxLength(40)] string Reference; [Required] decimal Amount; } // A document, on the other hand, is a shape other kinds of document build on. entity Document { [Required, MaxLength(200)] string Title; } entity Contract : Document { [Required, MaxLength(80)] string Counterparty; } ``` ## See also {#see-also} - [entity Sub : Base](https://osysharp.com/reference/entity/inheritance/) — what deriving actually gives you, and what it refuses - [entity](https://osysharp.com/reference/entity/declaration/) — the `entity` declaration itself - [security { }](https://osysharp.com/reference/security/entity-security/) — who may read and write a type, which sealing does not touch --- # Enums > A fixed set of named values, used as a member type. By default an enum stores as a compact number; add [Type(string)] to store the member's own name instead — what you want when a human or another system reads the column. [Label] gives a member the human-readable label a screen shows. Three answers you will want before you open a page. (1) Room.Members is every member, in declaration order — `foreach (var r in Room.Members)` is how you build a picker, a tab bar or a filter; never hardcode the list, and Enum.GetValues() is the same array if you prefer C#'s spelling. (2) A member may be named for its own type: `[Required] Room Room;` compiles, exactly as `Color Color` does in C#. (3) Text(p.Room) renders the [Label] label, but "in " + p.Room concatenates the raw member NAME ("LivingRoom") — say p.Room.Label wherever a string is what you need. Full detail: osy docs enum-declaration#members and osy docs enum-labels#label-property. ## Summary {#summary} An `enum` is a **fixed set of named values** — `enum Status { Draft, Placed, Cancelled }` — used as the type of a member. It gives you a closed vocabulary the compiler checks: a value outside the set is a compile error, not a bad row. Two small decisions round it out: **how it is stored** (a number, or its name) and **what a human sees** (its label). ## Description {#description} ### Declaring one {#declaring} An [enum](https://osysharp.com/reference/enum/declaration/) lists its members; any member or property can then take the enum as its type (an `entity Order { Status Status; }`, a function local, a component prop). The compiler enforces the set everywhere the enum is used, so a typo or a stale value is caught at compile time: ```osy title="a closed set the compiler checks" test app=enum-index enum Status { Draft, Placed, Cancelled } ``` ```osy title="proof: the members are distinct values" run app=enum-index [Test] void Status_is_a_fixed_set() { var s = Status.Placed; Assert.NotEqual(Status.Draft, s); } ``` ### Stored as a number, or as its name {#storage} By default an enum member is stored as a **number** — compact, and fine when only your own code reads it. When a human or another system will read the column, store it as the member's **own name** with `[Type(string)]`, so the value in the database is `"Placed"` rather than `1`. That is the setting to reach for on anything exported, reported on, or read by an integration. See [enum](https://osysharp.com/reference/enum/declaration/). ### The label a human reads {#labels} A member's stored value is compact; the label on screen doesn't have to be. [[Label], [Icon], [Tone] — what a human reads](https://osysharp.com/reference/enum/labels/) — `[Label("…")]` — gives a member a human-readable label (the member's own name is the default), and a doc comment gives it a longer description. So `InProgress` can show as "In progress" without changing what is stored. ## See also {#see-also} - [enum](https://osysharp.com/reference/enum/declaration/) — declaring the set, and `[Type(string)]` for name storage - [[Label], [Icon], [Tone] — what a human reads](https://osysharp.com/reference/enum/labels/) — `[Label]` and the human-facing label - [Types](https://osysharp.com/reference/types/index/) — the rest of the type system --- # [Label], [Icon], [Tone] — what a human reads > An enum member stores a compact value but shows a human-readable label. [Label("…")] gives a member its label (otherwise the member's own name is used), and a doc comment gives it a longer description. A screen that shows an enum-typed value — a grid cell, a text line — reads the label, never the stored value. [Icon(…)] and [Tone(…)] say which icon and which tone stand for a member, so every screen shows it the same way without repeating the decision. ## Summary {#summary} An enum member has two faces. It has a **stored value** — the compact thing that lives in the column and that your code compares against — and it has a **label**, the words a person reads on screen. `[Label("…")]` sets the label. Without one, the label is simply the member's name. You never have to convert between them. Show an enum-typed value anywhere in a screen and the label is what appears. ## Signature {#signature} ```osy syntax enum { [Label("