@chill-sharp/ui-core 1.1.12

package/doc/ComplianceGuide/README.md

@@ -0,0 +1,178 @@
+# Security And Compliance Guide
+
+Versione italiana: [Italiano](../it/ComplianceGuide/README.md)
+
+
+This document explains how ChillSharp can support security and compliance programs such as NIS2, ISO 27001, SOC 2, or internal secure-development policies.
+
+It is intentionally generic: compliance frameworks differ by jurisdiction and sector, but many of the underlying engineering controls are the same.
+
+Important: ChillSharp can help you implement and enforce several technical controls automatically, but using ChillSharp does not by itself make an application compliant. Compliance still depends on your hosting environment, operating procedures, monitoring, incident response, backup strategy, and legal scope.
+
+## Where ChillSharp Helps
+
+ChillSharp is useful when you want your API layer to apply the same validation, authorization, metadata, and audit conventions consistently across the whole model instead of re-implementing them controller by controller.
+
+That consistency matters in compliance work because many findings come from gaps between endpoints, forgotten checks in one update path, or UI and API behavior drifting apart over time.
+
+## Control Areas Supported By ChillSharp
+
+### 1. Input validation and data integrity
+
+ChillSharp helps reduce invalid or unsafe data entering the system by centralizing validation around the entity and query model.
+
+- standard DataAnnotations such as `[Required]`, `[StringLength]`, `[Range]`, and `[EmailAddress]` can be applied on `[ChillProperty]` members
+- the validation pipeline runs during explicit `VALIDATE()` flows
+- the same validation also runs automatically when the client goes directly to create or update
+- custom business validation can be added through `OnValidation()`
+
+This supports control objectives typically described as:
+
+- input validation
+- data quality enforcement
+- secure-by-default server-side validation
+- reduction of inconsistent validation across endpoints
+
+Reference:
+- [../ValidationModel/README.md](../ValidationModel/README.md)
+
+### 2. Authentication and controlled access
+
+With `ChillSharp.Auth`, the host can expose Identity-backed account flows for:
+
+- registration
+- login
+- refresh-token handling
+- password change
+- password reset
+
+This helps standardize the access layer and avoid ad-hoc authentication endpoints with inconsistent behavior.
+
+Reference:
+- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
+
+### 3. Authorization and least privilege
+
+ChillSharp provides a default-deny permission model with:
+
+- user permissions
+- role permissions
+- module, entity, and property scopes
+- allow/deny rules
+- explicit precedence rules
+
+This is useful for compliance programs that expect least-privilege access, separation of duties, and clear server-side enforcement of who can see or modify data.
+
+Because property-level permissions are part of the model, ChillSharp can help reduce a common risk: users having access to the right entity but too much access to sensitive fields.
+
+Reference:
+- [../PermissionModel/README.md](../PermissionModel/README.md)
+
+### 4. Audit trail fields on data changes
+
+`ChillEntity` automatically maintains:
+
+- `LastUpdate`
+- `LastUpdateUser`
+- `LastUpdateUtcOffset`
+- `Checksum`
+
+These values are updated as part of the runtime path used by ChillSharp during updates, which helps enforce a consistent minimum audit trail without depending on every derived entity to remember to do it manually.
+
+This supports common control objectives such as:
+
+- traceability of changes
+- accountability of user actions
+- basic integrity checking
+- evidence that records were modified, when, and by whom
+
+The checksum is especially useful as a lightweight integrity signal for synchronization, comparisons, and tamper detection scenarios inside the application model.
+
+Reference:
+- [../README.md](../README.md#audit-fields)
+
+### 5. Consistent schema metadata and safer client generation
+
+ChillSharp can expose schema metadata and generate clients from the API description.
+
+This does not replace a security control by itself, but it can reduce implementation drift between:
+
+- backend validation and frontend forms
+- backend authorization and frontend capabilities
+- actual API contracts and hand-written clients
+
+Reducing drift matters in audits because inconsistent clients and duplicated API glue often create hidden exceptions to the intended control model.
+
+Reference:
+- [../ClientGeneration/README.md](../ClientGeneration/README.md)
+
+## Why This Matters For NIS2 And Similar Frameworks
+
+Frameworks such as NIS2 usually do not certify a library. They expect organizations to implement risk-based technical and organizational measures.
+
+In that context, ChillSharp is best understood as a control-enforcement component that can help with:
+
+- identity and access control
+- least privilege
+- traceability of updates
+- consistent validation of incoming data
+- reduction of manual security plumbing
+
+This can lower the probability of common implementation defects and make the application easier to review during internal audits or external assessments.
+
+## What ChillSharp Does Not Solve On Its Own
+
+You still need to design and operate the broader security system around the library. In particular, ChillSharp does not by itself provide:
+
+- a full SIEM or centralized security logging strategy
+- incident detection and response procedures
+- vulnerability management and patch governance
+- infrastructure hardening
+- network segmentation
+- transport security configuration
+- encryption key management
+- secrets management
+- backup and disaster recovery processes
+- MFA policy and corporate identity governance
+- supplier risk management
+- legal interpretation of NIS2 or any other regulation
+
+Those controls belong partly to your application, but mostly to your platform and organizational processes.
+
+## Recommended Positioning In Audit Documentation
+
+When documenting ChillSharp in a security review, describe it as:
+
+- a framework that centralizes API validation
+- a framework that enforces role- and property-based authorization
+- a framework that maintains basic audit metadata on entity updates
+- a framework that reduces inconsistent custom CRUD code
+
+Avoid stronger claims such as:
+
+- "the application is NIS2 compliant because it uses ChillSharp"
+- "ChillSharp guarantees regulatory compliance"
+
+The stronger and more defensible statement is:
+
+"ChillSharp helps implement and automate several technical controls that are commonly required by security and compliance frameworks, while final compliance depends on the full system design and operating model."
+
+## Practical Checklist
+
+If you want to use ChillSharp as part of a compliance-oriented architecture, the baseline is:
+
+1. use `ChillEntity` and annotate exposed properties with `[ChillProperty]`
+2. add DataAnnotations and custom `OnValidation()` rules for business constraints
+3. enable `ChillSharp.Auth` for authenticated systems
+4. configure roles and permission rules with default-deny posture
+5. verify that `GetCurrentUserName()` is correctly implemented in your `IChillContext`
+6. preserve and monitor `LastUpdate`, `LastUpdateUtcOffset`, `LastUpdateUser`, and `Checksum`
+7. secure the host with HTTPS, logging, backups, patching, and operational controls outside ChillSharp
+
+## Related Documents
+
+- [../ValidationModel/README.md](../ValidationModel/README.md)
+- [../AuthenticationModel/README.md](../AuthenticationModel/README.md)
+- [../PermissionModel/README.md](../PermissionModel/README.md)
+- [../ClientGeneration/README.md](../ClientGeneration/README.md)
+- [../RegisterContext.md](../RegisterContext.md)

package/doc/Configuration/README.md

@@ -0,0 +1,94 @@
+# ChillSharp Configuration Reference
+
+Versione italiana: [Italiano](../it/Configuration/README.md)
+
+
+This document lists the environment variables currently used by ChillSharp and by the example ChillSharp host in `ChillSharp.Examples/BloggingApiService`.
+
+Use it as a quick reference when configuring Docker, `docker compose`, or another deployment target.
+
+At startup, `AddChillApi<TContext>()` writes all `CHILLSHARP_` and `CHILL_SHARP_` process environment variables to the console. Variable names containing `PASSWORD` are masked as `********`.
+
+## Hosting
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| ASP.NET Core listen URLs | `ASPNETCORE_URLS` | URLs bound by the ASP.NET Core host. | `http://+:8080` |
+| ASP.NET Core environment | `ASPNETCORE_ENVIRONMENT` | Standard ASP.NET Core environment name. | `Development` in the example `.env` |
+
+## Core API
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| SQLite database path | `CHILLSHARP_DB_PATH` | File path used by the example `BloggingContext` SQLite database. | `/data/blogging.db` |
+| Primary culture | `CHILLSHARP_PRIMARY_CULTURE` | Value returned by `IChillContext.GetPrimaryCultureName()`. | `en-GB` |
+| Secondary culture | `CHILLSHARP_SECONDARY_CULTURE` | Value returned by `IChillContext.GetSecondaryCultureName()`. | `it-IT` |
+| Protected core API | `CHILLSHARP_API_PROTECTED` | Requires authentication for the core ChillSharp API when `true`. | `true` when auth is enabled |
+| DTO system time zone | `CHILLSHARP_SYSTEM_TIMEZONE` | IANA time-zone id used by ChillSharp DTO `DateTime` and `DateTimeOffset` parsing and serialization helpers. | `Europe/Rome` |
+
+## Module Toggles
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| Enable schema module | `CHILLSHARP_ENABLE_SCHEMA` | Registers `ChillSharp.Schema` services. | `true` |
+| Enable auth module | `CHILLSHARP_ENABLE_AUTH` | Registers `ChillSharp.Auth` account and auth-management services. | `true` |
+| Enable i18n module | `CHILLSHARP_ENABLE_I18N` | Registers `ChillSharp.I18n` services. | `true` |
+| Enable MCP module | `CHILLSHARP_ENABLE_MCP` | Registers `ChillSharp.Mcp` services and maps the MCP endpoint when the host context supports schema metadata. | `true` |
+| Enable attachment module | `CHILLSHARP_ENABLE_ATTACHMENT` | Registers `ChillSharp.Attachment` services and endpoints when the host context supports attachments. | `false` in the example host, set `true` when the context implements attachments |
+
+## Attachment Storage
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| Attachment archive root | `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT` | Root folder used by `ChillSharp.Attachment` to read and store archived files. | `attachments` under the host base directory |
+
+## Auth Tokens And Password Flows
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| Access-token lifetime | `CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES` | Minutes before a ChillSharp bearer access token expires. Read directly by `ChillAuthIdentityApiOptions` and `ChillIdentityApiOptions` unless the host overrides `AccessTokenLifetime` in code. | `20` |
+| Refresh-token lifetime | `CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS` | Days before a refresh token expires. Read directly by `ChillAuthIdentityApiOptions` and `ChillIdentityApiOptions` unless the host overrides `RefreshTokenLifetime` in code. | `14` |
+| Return reset token in API response | `CHILLSHARP_AUTH_RETURN_PASSWORD_RESET_TOKENS` | Includes `userId` and `resetToken` in `/api/chill-auth/account/request-password-reset` response when `true`. | `false` in the example host |
+| Send password-reset emails | `CHILLSHARP_AUTH_SEND_PASSWORD_RESET_EMAILS` | Sends a password-reset email through SMTP when `true`. | `false` in code, `true` in the example `.env` |
+| Password-reset email subject | `CHILLSHARP_AUTH_PASSWORD_RESET_SUBJECT` | Subject used for password-reset emails. | `Reset your password` |
+| Password-reset URL | `CHILLSHARP_AUTH_PASSWORD_RESET_URL` | Optional frontend URL used to build a clickable password-reset link with `userId` and `resetToken`. | unset |
+
+## SMTP Password-Reset Delivery
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| SMTP host | `CHILLSHARP_SMTP_HOST` | SMTP server host name used for no-reply password-reset delivery. | unset |
+| SMTP port | `CHILLSHARP_SMTP_PORT` | SMTP server port. | `587` |
+| SMTP SSL/TLS | `CHILLSHARP_SMTP_ENABLE_SSL` | Enables SSL/TLS on the SMTP client when `true`. | `true` |
+| SMTP user name | `CHILLSHARP_SMTP_USERNAME` | SMTP authentication user name. | unset |
+| SMTP password | `CHILLSHARP_SMTP_PASSWORD` | SMTP authentication password. | unset |
+| No-reply sender email | `CHILLSHARP_SMTP_FROM_EMAIL` | Sender email address used for password-reset emails. | unset |
+| No-reply sender display name | `CHILLSHARP_SMTP_FROM_DISPLAY_NAME` | Sender display name used for password-reset emails. | unset |
+
+When `CHILLSHARP_AUTH_SEND_PASSWORD_RESET_EMAILS=true`, the SMTP host and sender email must be configured or the reset flow will fail.
+
+## Root User Bootstrap
+
+These variables are read by `ChillAuthRootUserInitializer<TUser>` during startup when root-user initialization is enabled.
+
+| Option | ENV variable | Description | Default |
+| --- | --- | --- | --- |
+| Initialize root user | `CHILLSHARP_AUTH_INITIALIZE_ROOT_USER` | Creates the root Identity user at startup when credentials are available. | `true` |
+| Create linked ChillSharp auth user | `CHILLSHARP_AUTH_CREATE_ROOT_AUTH_USER` | Also creates the linked ChillSharp `AuthUser` with permission-management access. | `true` |
+| Root user name | `CHILLSHARP_AUTH_ROOT_USERNAME` | Login name for the bootstrap administrator. | unset |
+| Root password | `CHILLSHARP_AUTH_ROOT_PASSWORD` | Password for the bootstrap administrator. | unset |
+| Root email | `CHILLSHARP_AUTH_ROOT_EMAIL` | Optional email for the bootstrap administrator. | unset |
+| Root display name | `CHILLSHARP_AUTH_ROOT_DISPLAY_NAME` | Display name copied into the linked ChillSharp `AuthUser`. | `Root` in code |
+
+## Notes
+
+- Most variables listed here use the example host's `CHILLSHARP_*` prefix. `CHILLSHARP_SYSTEM_TIMEZONE` is a core ChillSharp runtime variable used directly by DTO date/time mapping.
+- Startup console output includes both `CHILLSHARP_*` and `CHILL_SHARP_*` variables. `PASSWORD` values are masked, but other values are printed as-is.
+- `CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES` and `CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS` are built-in ChillSharp auth defaults. Positive integer values are accepted; invalid, zero, or negative values fall back to the code defaults.
+- `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT` is read by `ChillSharp.Attachment` directly and should point at a persistent volume in Docker.
+- `CHILLSHARP_SYSTEM_TIMEZONE` expects an IANA time-zone id such as `Europe/Rome` or `America/New_York`.
+- `CHILLSHARP_SYSTEM_TIMEZONE` affects `DateTime` and some `DateTimeOffset` normalization paths. `DateOnly` and `TimeOnly` keep standard .NET string output.
+- The `CHILLSHARP_*` variables listed here are consumed either by ChillSharp itself or by the example host startup code.
+- If you build your own host application, you can keep these names or map configuration differently in your own startup code.
+- For deployment examples, also see [doc/HowTo/05-docker-env-variables.md](../HowTo/05-docker-env-variables.md).
+- For the full date/time serialization reference and examples, see [doc/DateTimeSerialization.md](../DateTimeSerialization.md).

package/doc/CurrentUserPreferences.md

@@ -0,0 +1,114 @@
+# Current User Preferences
+
+Versione italiana: [Italiano](./it/CurrentUserPreferences.md)
+
+`ChillSharp.Auth` can make the authenticated user's display preferences available to entity lifecycle hooks without querying `AuthUser` during every save.
+
+The immutable `ChillUserPreferences` snapshot contains:
+
+- `DisplayCultureName`
+- `DisplayTimeZone`
+- `DisplayDateFormat`
+- `DisplayNumberFormat`
+- `PreferredTheme`
+
+## Registration And Cache Lifecycle
+
+`AddChillAuthApi<TContext>()` registers a singleton `IChillAuthUserPreferencesCache` and scoped `IChillAuthUserPreferencesAccessor`.
+
+When the user logs in or refreshes a token, ChillSharp loads the matching `AuthUser` once and warms a snapshot keyed by its `ExternalId`. The accessor only reads that in-memory snapshot during requests; it does not query the user table.
+
+`ChillAuthService` refreshes the cached snapshot after creating or updating an `AuthUser`. It invalidates a deleted user's snapshot and both the previous and new keys when `ExternalId` changes.
+
+The cache stores scalar preference values, never a tracked EF Core `AuthUser` instance.
+
+## Current User Preferences API
+
+Authenticated clients can retrieve the same snapshot used by server-side code with:
+
+```http
+GET /api/chill-auth/current-user-preferences
+Authorization: Bearer <access token>
+```
+
+The response is a `ChillUserPreferences` JSON object:
+
+```json
+{
+  "displayCultureName": "it-IT",
+  "displayTimeZone": "Europe/Rome",
+  "displayDateFormat": "dd/MM/yyyy",
+  "displayNumberFormat": "N2",
+  "preferredTheme": "cini"
+}
+```
+
+Use this endpoint after login and when restoring an authenticated UI session. It is the source of truth for the language/culture, time zone, date format, and number format used by the API client and UI; do not derive those values from the browser, operating system, token claims, or an auth-management endpoint.
+
+The C# client exposes `GetCurrentUserPreferences()`. The Python client exposes `get_current_user_preferences()`, while the TypeScript client and Angular wrapper expose `getCurrentUserPreferences()`. The Vue and React packages additionally provide `useCurrentUserPreferences()`.
+
+In the Angular UI Core package, inject `ChillService` and consume its `userPreferences` signal or the individual `displayCultureName`, `displayTimeZone`, `displayDateFormat`, `displayNumberFormat`, and `preferredTheme` projections. Use them for UI text culture, date and number format/parse operations, UTC-to-local time conversion, and the selected theme.
+
+`PreferredTheme` is an opaque string: the backend stores and returns it without knowing which themes a client provides. UI Core uses the browser's `prefers-color-scheme` choice (`bright` or `dark`) when there is no authenticated preference. Client applications can declare additional selectable themes when they register UI Core:
+
+```ts
+provideChillSharpUiCore({ additionalThemes: ['cini'] })
+```
+
+The built-in choices are `bright`, `dark`, and `soft`. If an authenticated user's stored value is not available in that client, UI Core falls back to the browser light/dark preference.
+
+## Host DbContext
+
+`IChillContext.GetCurrentUserPreferences()` returns `ChillUserPreferences.Empty` by default. In an auth-enabled custom host context, inject `IChillAuthUserPreferencesAccessor` and delegate to it:
+
+```csharp
+using ChillSharp;
+using ChillSharp.Auth.Services;
+
+public class AppDbContext : DbContext, IChillContext, IChillAuthDbContext
+{
+    private readonly IChillAuthUserPreferencesAccessor? _userPreferencesAccessor;
+
+    public AppDbContext(
+        DbContextOptions<AppDbContext> options,
+        IChillAuthUserPreferencesAccessor? userPreferencesAccessor = null)
+        : base(options)
+    {
+        _userPreferencesAccessor = userPreferencesAccessor;
+    }
+
+    public ChillUserPreferences GetCurrentUserPreferences() =>
+        _userPreferencesAccessor?.Current ?? ChillUserPreferences.Empty;
+
+    public string GetDefaultUserCultureName()
+    {
+        var cultureName = GetCurrentUserPreferences().DisplayCultureName;
+        return string.IsNullOrWhiteSpace(cultureName)
+            ? GetPrimaryCultureName()
+            : cultureName;
+    }
+}
+```
+
+The optional constructor parameter keeps design-time creation and tests that construct the context directly compatible. A normal dependency-injection-created context receives the accessor.
+
+`ChillAuthDbContext` already implements this pattern.
+
+## Entity Lifecycle Hooks
+
+Use the snapshot directly from the supplied `IChillContext`. No database access is required in the hook.
+
+```csharp
+public override void OnUpdate(IChillContext context)
+{
+    var preferences = context.GetCurrentUserPreferences();
+    var timeZone = preferences.DisplayTimeZone;
+
+    if (!string.IsNullOrWhiteSpace(timeZone))
+    {
+        // Apply application-specific time-zone behavior.
+    }
+}
+```
+
+All values can be empty for background jobs, unauthenticated calls, or a user without a matching `AuthUser`. Treat them as optional and choose an application fallback. Validate `DisplayTimeZone` before using it as a time-zone identifier.

package/doc/DateTimePolicy/README.md

@@ -0,0 +1,154 @@
+# ChillSharp DateTime Policy
+
+Versione italiana: [Italiano](../it/DateTimePolicy/README.md)
+
+
+This document defines the ChillSharp DTO policy for `DateTime` and `DateTimeOffset` values.
+
+The policy applies when ChillSharp reads or writes values through DTO property bags, such as `ChillDtoEntity.Properties` and `ChillDtoQuery.Properties`.
+
+## System Time Zone
+
+ChillSharp uses a configured system time zone when a DTO value does not carry an explicit offset.
+
+Environment variable:
+
+```text
+CHILLSHARP_SYSTEM_TIMEZONE
+```
+
+Default:
+
+```text
+Europe/Rome
+```
+
+Use an IANA time-zone id, for example:
+
+```text
+Europe/Rome
+America/New_York
+UTC
+```
+
+This configured time zone is not the same thing as `DateTimeKind.Local`. `DateTimeKind.Local` means the operating system local time zone. ChillSharp uses its own configured time zone explicitly.
+
+## Incoming DTO Values
+
+Incoming values are values received from a client and applied to CLR properties.
+
+### DateTimeOffset
+
+`DateTimeOffset` preserves an explicit offset when the client sends one.
+
+Examples:
+
+```text
+2026-04-11T14:30:00.0000000+02:00
+2026-04-11T12:30:00.0000000Z
+```
+
+Policy:
+
+- if the incoming value has `Z`, preserve it as a UTC `DateTimeOffset`
+- if the incoming value has an explicit offset, preserve that offset
+- if the incoming value has no offset, interpret it as local time in `CHILLSHARP_SYSTEM_TIMEZONE`
+- store the resulting value as a `DateTimeOffset` with the resolved offset
+
+Example with `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
+
+```text
+Incoming: 2026-04-11T14:30:00
+Stored:   2026-04-11T14:30:00+02:00
+```
+
+### DateTime
+
+`DateTime` represents an instant and is normalized to UTC when read from DTO input.
+
+Policy:
+
+- if the incoming value has `Z`, parse it as UTC
+- if the incoming value has an explicit offset, parse it as that instant
+- if the incoming value has no offset, interpret it as local time in `CHILLSHARP_SYSTEM_TIMEZONE`
+- store the resulting value as a UTC `DateTime`
+- set `DateTime.Kind` to `DateTimeKind.Utc`
+
+Example with `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
+
+```text
+Incoming: 2026-04-11T14:30:00
+Stored:   2026-04-11T12:30:00Z
+Kind:     Utc
+```
+
+Example with an explicit offset:
+
+```text
+Incoming: 2026-04-11T14:30:00+02:00
+Stored:   2026-04-11T12:30:00Z
+Kind:     Utc
+```
+
+## Outgoing DTO Values
+
+Outgoing values are CLR values serialized into DTO property bags before returning data to a client.
+
+### DateTimeOffset
+
+ChillSharp serializes `DateTimeOffset` as an ISO 8601 string with its offset.
+
+```text
+2026-04-11T14:30:00.0000000+02:00
+```
+
+### DateTime
+
+ChillSharp serializes `DateTime` as an ISO 8601 string with an explicit offset.
+
+Policy:
+
+- if the source value is UTC, convert it to `CHILLSHARP_SYSTEM_TIMEZONE` for DTO output
+- if the source value is unspecified, interpret it as local time in `CHILLSHARP_SYSTEM_TIMEZONE`
+- emit an ISO 8601 string with the resolved offset
+
+Example with `CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome`:
+
+```text
+CLR:      2026-04-11T12:30:00Z
+DTO:      2026-04-11T14:30:00.0000000+02:00
+```
+
+Depending on the JSON serializer, the `+` character may appear as `\u002B` on the wire:
+
+```json
+"2026-04-11T14:30:00.0000000\u002B02:00"
+```
+
+That is valid JSON and clients read it back as `+02:00`.
+
+## Database Guidance
+
+This policy is designed to work cleanly with providers such as PostgreSQL/Npgsql.
+
+Recommended mapping:
+
+- use `DateTime` for instant values that should be persisted as UTC
+- use `DateTimeOffset` when preserving the incoming offset matters
+- use `DateOnly` and `TimeOnly` for calendar dates or times of day that are not instants
+
+For PostgreSQL:
+
+- `DateTime` values produced by DTO parsing are UTC and are suitable for `timestamp with time zone`
+- local wall-clock values should not be modeled as `DateTime` unless converting them to UTC is intended
+
+## Server-Managed Audit Fields
+
+ChillSharp server-managed audit fields are ignored when applying incoming entity DTO values:
+
+- `Checksum`
+- `LastUpdateUser`
+- `LastUpdate`
+- `LastUpdateUtcOffset`
+
+Clients may receive these values from DTO output, but sending them back does not overwrite the server-managed entity state.