Workable.Views 1.1.91326.1

• net10.0

  • Workable.Abstractions (>= 1.1.91326.1)

# 1.1.091326.1

Date: 2026-09-13

These notes describe only the user-visible, operational, and public API differences from `1.1.083126.1`. Intermediate implementation details are omitted.

## Breaking Changes

- There are no intentional breaking API changes in this release. Runtime scheduling is additive and remains disabled unless a work system explicitly enables it and an `IWorkScheduleStore` is registered.

## Runtime Scheduling

- Authorized callers can durably schedule registered work for one future execution, a fixed elapsed-time interval, or a calendar schedule expressed with a five-field cron expression and an explicit IANA time zone.
- Schedules belong to one Workable system and target work by definition name because runtime work ids are regenerated when a system starts. Every occurrence resolves and validates the latest registered definition.
- Interval schedules support a caller-selected first run and intervals of at least one minute. Cron schedules account for time-zone daylight-saving gaps and overlaps and support server-side previews of the next five occurrences.
- Each schedule controls whether one overdue occurrence should run after system downtime. Recurring schedules advance directly to the next future occurrence rather than producing a burst for every elapsed interval.
- Scheduler availability is tracked per host and logical system, so a new host joining during a rolling deployment does not mistake its own startup boundary for full-system downtime and skip valid work.
- Runtime schedules and worker recurrence remain separate features. Definitions with statically configured recurrence can be scheduled once but cannot be given another recurring runtime schedule. If recurrence is enabled on a definition after a recurring schedule is created, scheduled workers explicitly suppress worker recurrence.
- Scheduled dispatch always uses `StartAndReturnAfterAccepted`. The background scheduling loop never inherits `DoNotStart` or waits for a future worker to complete, while normal worker failure, retry, auto-cancellation, concurrency, logging, and retention policies continue to apply after queue acceptance.
- Accepted occurrences create independent workers. Dispatch history records whether an occurrence was accepted, rejected, skipped, or failed and links accepted occurrences to their workers without treating eventual worker completion as part of schedule dispatch.

## Authorization and Security

- Schedule creation uses the definition's existing `Queue` permission, queue requirements, invocation rules, input validation, and effective worker configuration. Scheduling does not introduce a separate permission that could bypass ordinary execution controls.
- A successful creation check becomes the schedule's durable execution grant. Disabling or deleting the creator or changing their group membership does not silently revoke an accepted schedule; cancel the schedule to revoke that delegation.
- The durable grant cannot acquire unrestricted profile-capture capability from a later definition change. Each definition also exposes `ScheduleSecurityVersion`, allowing a deployment to reject older schedules when the authority or business scope of the work changes.
- Schedule reads and occurrence history require the definition's current `Read` permission. Removed definitions fail closed to an explicit system-level `ReadAllWork` grant, and hidden or unauthorized schedules use non-disclosing not-found behavior.
- Schedule cancellation uses the definition's current `Cancel` permission. `WhenScheduleActionsRequire(...)` supports schedule-specific constraints, while shared `WhenOperatingRequire(...)` constraints continue to apply. Worker-action-only constraints do not become unconstrained schedule access.
- Creator and canceler identity fields are bounded and rejected instead of truncated. Schedule and occurrence queries enforce row and serialized-payload limits before returning authorized data.
- Configurable per-system, per-definition, and per-actor admission limits bound active and retained schedules. Independent byte, occurrence-history, query, claim-batch, and cleanup limits prevent repeated create/cancel operations or large retained payloads from creating unbounded storage and dispatch pressure.

## SQL Server Persistence and Dispatch

- `Workable.SqlServer` now supplies the built-in `IWorkScheduleStore`. Register SQL persistence at host scope and enable scheduling independently for each work system with `EnableScheduling(...)` or `UseScheduling(...)`.
- Automatic deployment and the schema CLI recognize scheduling as an independent schema component. This is the first released scheduling schema: fresh databases and databases upgraded from `1.1.083126.1` receive empty current scheduling tables, and no scheduling data is backfilled or migrated.
- SQL persistence isolates schedules by persistence scope and logical Workable system name and enforces admission, retention, serialized-byte, and rolling occurrence-history limits transactionally across hosts.
- Per-host availability observations share the existing claim round trip and avoid a system-wide heartbeat lock. Graceful shutdown makes a best-effort close within its own one-second bound; a short lease bounds stale availability after a slow provider or abrupt process loss.
- Definition names are limited to the SQL schedule table's 450-character durable column bound, with oversized names reported as structured invalid schedule creation.
- Schedule creation, occurrence completion, and cleanup acquire their per-system coordination range in one consistent order, preventing index lock cycles while preserving independent progress for different Workable systems.
- Due schedules use fenced leases and an atomic dispatch-start marker. An accepted cancellation cannot be followed by dispatch from a stale claimant, and an expired or superseded claimant does not queue work.
- Delivery remains at least once across the narrow failure window where queueing succeeds but occurrence persistence fails. Work whose duplicate execution would be unsafe should continue to use Workable idempotency or application-level idempotency.
- Schedule occurrence history and terminal schedules expire according to the configured retention period, which defaults to one day and can be configured from one minute through seven days. Compact per-system usage rows avoid repeatedly scanning complete occurrence history while preserving exact transactional quotas.
- Scheduler hosts claim bounded batches and dispatch each batch concurrently. While due work remains they immediately claim the next batch; the one-second fallback poll is reserved for idle cross-process discovery and error recovery rather than acting as a throughput ceiling.

## HTTP API and Admin UI

- The built-in HTTP API adds routes to create and list schedules, page upcoming schedules by next-run time, load a management overview, read one schedule, list retained occurrences, cancel an active schedule, and preview cron occurrences. Named work systems expose the same routes under their existing system-scoped path.
- Host and system capability discovery now reports whether scheduling is available, allowing clients to hide scheduling controls when no durable schedule store is configured.
- The queue dialog adds a **Schedule** action alongside **Queue** and **Watch** when scheduling is available. It reuses the existing input and runtime configuration, supports one-time, interval, and cron timing, previews cron occurrences, and exposes the missed-execution option.
- Each enabled system adds **Schedules** after **Iterations** in the explorer tree. The screen separates upcoming executions from retained schedules, displays recent dispatch history and accepted-worker links, and supports creating or canceling schedules.
- The schedule screen loads the first 25 recent schedules, the first 25 upcoming schedules, exact readable schedule totals, its selection, and retained dispatch history through one overview request backed by one SQL command. Each list has a fixed-height viewport with sticky headings and automatically continues its independent cursor as the user scrolls. A sliding five-page, 125-record client window bounds polling, rendering, and retained client state; polls authoritatively replace the current provider-ordered cursor window, while controls can return to the newest or soonest window. Visible-page polling uses randomized jitter, prevents overlapping refreshes, exponentially backs failures off to a one-minute ceiling, and refreshes immediately when the tab becomes visible.
- Schedule paging, cancellation, and definition-picker requests are scoped to the selected host and logical-system generation, and changing that target closes open schedule-creation dialogs. Core bounds every custom-provider overview collection to the requested limit and includes occurrences only for the selected schedule, including when authorization is disabled. The custom-provider compatibility query is capped at 1,000 readable active schedules; providers supporting larger active sets must override the optimized upcoming query instead of making one request enumerate an arbitrary number of rows.
- **New schedule** opens the catalog picker and then the existing queue configuration dialog in scheduling mode. Recurring runtime controls are disabled for definitions that already have static recurrence.

## Public API and Configuration

- Added `IWorkScheduler` to work systems and caller-scoped sessions, together with schedule identifiers, timing, request, snapshot, cursor-paginated query, consolidated overview, occurrence, creation, and cancellation contracts.
- Added `IWorkScheduleStore` as the persistence abstraction for custom providers. Enabling scheduling without a store fails system startup instead of accepting non-durable schedules.
- Added `WorkSystemSchedulingConfiguration` for history retention, active and retained schedule quotas, per-actor quotas, schedule and occurrence payload limits, bounded claim batches, query budgets, and cleanup behavior.
- Added schedule-aware authorization requirement context and builder methods, HTTP schedule request and response contracts, capability discovery fields, and the developer-controlled definition security version.
- The complete in-process and HTTP management surfaces are available in this release. MCP and SignalR do not currently expose schedule management.

## Performance

- Focused SQL baselines measured 276.55 ms for 25 simultaneous completions at the 10,000-occurrence boundary, 865.78 ms for the equivalent sequential case, and 328.82 ms to complete one occurrence while pruning a 100,000-entry retained history.
- End-to-end backlog baselines measured 590.1 ms for 25 simultaneously due schedules, 1.655 seconds for 100, and 12.737 seconds for 1,000. Batch count and payload-byte limits bound host and database pressure.
- The 100,000-worker in-memory queue baseline remained within run variance with scheduling disabled at 1.427 seconds and enabled but idle at 1.445 seconds.
- Maximum-page recent, active, and continued-active schedule queries measured 27.98, 26.55, and 23.50 ms with 1,000 retained schedules, and 41.61, 36.27, and 37.96 ms with 10,000. The consolidated 100-row overview measured 102.48 ms and 593.82 KiB at 1,000 retained schedules, and 124.29 ms and 569.30 KiB at 10,000.

## Deployment Notes

- Scheduling is opt-in. Register `AddWorkableSqlServerPersistence(...)` once for the host and call `EnableScheduling(...)` for each work system that should expose scheduling.
- SQL schema auto-deployment creates the scheduling tables when scheduling is first required. Deployments that disable automatic schema deployment must apply the generated scheduling schema before starting an enabled system.
- The Sample Host's checked-in SQL deployment script includes the scheduling schema, and an automated parity test keeps that artifact synchronized with the runtime/CLI generator.
- Schedules use work definition names as their stable target. Renaming or removing a definition leaves its retained schedules orphaned until the name is restored or a caller with system-wide operate access cancels them. A one-time schedule becomes terminal after its rejected dispatch and then ages out; a recurring orphan remains active so restoring the definition name can resume future occurrences.
- Review the default admission, retained-history, payload, batch, and cleanup limits for each deployment. Increase them only with corresponding database-capacity and workload testing.
- Use stable IANA time-zone identifiers such as `UTC`, `America/Los_Angeles`, or `Europe/London` when schedules may be processed by different hosts.

## Documentation and Testing

- Added a runtime scheduling guide and updated the root, documentation, HTTP API, authorization, public API, project structure, registration, recurrence, SQL Server, sample-host, performance-harness, and admin UI documentation.
- Added behavior-focused coverage for timing calculation, cron and daylight-saving handling, missed executions, latest-definition resolution, recurrence suppression, forced background start behavior, durable grants and revocation, schedule visibility and cancellation, admission and payload limits, leases, cancellation races, retention, schema deployment, HTTP routes, and admin UI workflows.
- The final validation passed 2,504 core/API tests, 198 SQL Server tests, and 464 admin UI tests. Core/API branch coverage measured 96.28 percent and SQL Server source-condition coverage measured 95.74 percent. The scheduling UI changes meet the changed-branch coverage gate, and the SQL suite includes 50 synchronized create-versus-cleanup races that verify the shared lock order under contention.
- The complete 186-case baseline benchmark suite ran for 41 minutes 27 seconds without failed reports or critical validation errors. Focused reruns covered backlog draining, schedule creation, completion contention, and the final query and overview paths.