Reading a capability's source

Summary#

Prints the source of a capability. using Osyrin.Memory; puts real entities — real tables, with their own access rules — into your app, but that source lives inside the platform rather than in your project, so no amount of searching your own files will find it. osy source is how you read it. Offline: no server, no account, no database.

Signature#

osy source [name] [--json]

name is a capability (Osyrin.Memory, or just memory) or a type it declares (MemoryChunk). Omit it to list every capability with what it declares.

Description#

A capability is opted into per app in app.osy (use Osyrin.Memory;) and per file (using Osyrin.Memory;). What you get in return is a set of declared types. Those types are not abstract: they become tables in your app's own database, carrying the access rules the capability declares.

Because the source is embedded in the platform, three ordinary ways of answering "what did I just agree to" do not work — you cannot open the file, you cannot grep for it, and it is not in your version control. That gap is what this command closes.

It only ever reads. A capability declares types; the behaviour behind them is the platform's own. So there is no useful copy to take: a local fork would be a declaration with nothing implementing it, which would compile, shadow the real one, and then be wrong. The one supported change to a capability entity is its security, and that is written as a partial entity block in your own source:

```osy title="stating security for an entity a using brought in" test app=local-reading-a-capability app Invoicing { use Osyrin.Storage; }

// use in the manifest takes the DEPENDENCY; using brings its types into THIS file's scope — the same split C# // makes between a package reference and a using directive. A partial entity resolves its target through the // file's usings, so both lines are needed. using Osyrin.Storage;

[Role] enum AppRole { Staff } [Principal] entity User { string Email; }

// FileAsset is declared by using Osyrin.Storage; — this app never declares it, and cannot. // A partial adds no fields and changes no shape; it states who may reach the type. partial entity FileAsset { security { allow read when IsAuthenticated; } }

For an entity the capability leaves ungoverned — as `FileAsset` is above — what you write is the whole rule.

Some capability tables arrive already governed, because their rows belong to one signed-in user and only the
capability knows that: a chat conversation is yours, not the app's. There your partial **adds** to the rule already
there rather than replacing it, so you can grant a support role extra reach without being able to take the owner's
access away. See [capability rows that belong to a user](/reference/security/capability-row-ownership/).

> The UI kit is the exception, and deliberately so. A kit control is presentational — the source you read *is* the
> implementation — so it is meant to be forked. `osy kit` browses it and `osy get ui/<control>` vendors a copy into
> your project to change. See [Osyrin.Ui (the UI kit)](/reference/ui/kit/).

## Examples       {#examples}

Every capability, and what each declares:

```console
osy source

Platform capabilities — opt in per file with `using <name>;` (and in app.osy)

  Osyrin.Llm.Observability
    LlmAuditEntry, LlmCallLog, LlmStopReason, LlmToolCallLog
  Osyrin.Memory
    ContextType, EntityContext, FileChunk, Reference, ReferenceKind, …
  Osyrin.Storage
    FileAsset, FileGrant, FileGrantLevel, Folder, UploadedFile

The core baseline — in every app; no `using` opts in, and none can opt out

  Osyrin (13 files)
    ActionState, Align, AuditKind, ConnState, Connection, Continuation, … (+32)

The core baseline is the last section, and it is not one of the choices above it: those tables — the workflow runtime, the markdown store, the OAuth grant store — are in your app whether you ask for them or not. Read it with osy source core.

One capability's whole source, comments and all:

osy source Osyrin.Memory

Or start from a type you met in osy model output or in an error, and let it find the using:

osy source LlmCallLog

# LlmCallLog is declared by `using Osyrin.Llm.Observability;`
# Capabilities/Osyrin.Llm.Observability.osy

See also#

• Explaining your app's security — which of these your app has actually opted into, and who can read each one, including the core baseline every app carries
• Understanding your app — the resolved model, with capability types bound exactly as the server binds them
• Osyrin.Ui (the UI kit) — the kit, which is read the same way but is meant to be forked