@stacksjs/defaults 0.75.422 → 0.75.431

package/ai/skills/stacks-alias/SKILL.md

@@ -41,6 +41,14 @@ into another package's unpublished types is the problem. Avoid the former rule
 that all relative imports are forbidden, since framework code itself uses them
 to keep internal modules and cycle boundaries explicit.
 
+The five source tsconfigs use manifest-derived package names and public exports,
+not namespace-to-directory wildcards. Run
+`bun .github/scripts/generate-workspace-aliases.ts` after changing a workspace
+manifest and use `--check` to verify freshness. The owning helpers and source
+exceptions are documented in `core/alias/README.md`. External packages such as
+STX's `@stacksjs/desktop` keep normal package resolution; `core/desktop` owns
+`@stacksjs/desktop-build`.
+
 ## Verification
 
 Source: `core/alias/src/index.ts`, active tsconfig.json and the build/runtime

package/ai/skills/stacks-arrays/SKILL.md

@@ -198,10 +198,12 @@ zScore([1, 2, 3, 4], 3)           // 0.447...
 percentile([1, 2, 3, 4, 5], 50)   // 3       -- interpolated percentile
 percentile([1, 2, 3, 4], 25)      // 1.75    -- linear interpolation
 // Note: takes percentile value (0-100), uses linear interpolation
+// Throws for an empty array (like median) and a RangeError outside 0-100
 
 interquartileRange([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
 // Q3 median - Q1 median
-// Splits array at midpoint, computes median of each half
+// Sorts, splits at the midpoint, computes the median of each half
+// One number gives 0; an empty array throws
 
 covariance([1, 2, 3, 4], [1, 2, 3, 4])     // 1.25  -- positive correlation
 covariance([1, 2, 3, 4], [4, 3, 2, 1])     // -1.25 -- negative correlation

package/ai/skills/stacks-build/SKILL.md

@@ -86,6 +86,9 @@ buddy build --server --verbose --project [name]
 
 ## Standard Build Pattern
 
+For workspace dependency ordering, failure propagation and umbrella builds, read
+[the build package's workspace contract](../../../../core/build/README.md#workspace-builds).
+
 For a library barrel or a package with public subpaths, preserve the module
 graph with the shared transpiler. Identifier-minifying bundles have produced
 invalid re-export bindings on supported Bun versions. Separate bundles also

package/ai/skills/stacks-cache/SKILL.md

@@ -22,10 +22,11 @@ const products = await cache.mget<{ name: string }>(['product:42', 'product:43']
 // mget returns a record keyed by cache key, not an array.
 ~~~
 
-- TTL is in seconds. Zero means forever; omitted TTL uses the factory's
-  stdTTL, which defaults to zero. The exported cache/memory singleton is a
-  memory instance with no default expiry. Config's ttl value does not silently
-  turn that singleton into a configured Redis instance.
+- TTL is in seconds. Zero means forever; an omitted TTL uses the store's
+  default. For the `cache` export that is `ttl` from config/cache.ts (3600 as
+  shipped) on every driver, memory included, so a value set with no TTL
+  expires after an hour. The `memory` export is a separate in-process
+  instance with no default expiry.
 - `setForever` stores without expiry; `getTtl` reads remaining TTL and
   `ttl(key, seconds)` updates it. Missing values are undefined.
 - `mset([{ key, value, ttl? }])` writes entries. `del(keyOrKeys)` and
@@ -60,11 +61,14 @@ deploys, pointing `path` at a file the deploy preserves (the app's own SQLite
 database works; the table is the driver's alone). `createCache(driver,
 options?)` selects one of memory, redis, singlestore or sqlite.
 
-The `cache` export is the driver `config/cache.ts` selects (`driver`, with
-`prefix` and `ttl` applied to the non-memory drivers), resolved on first use
-and once the app's config has loaded. With the default `driver: 'memory'` it
-answers from the `memory` instance itself. `cacheFromConfig(settings?)` builds
-the same choice explicitly; `resetConfiguredCache()` forgets it.
+The `cache` export is the driver `config/cache.ts` selects, with its `prefix`
+and `ttl` applied on every driver (memory also takes `maxKeys`, `useClones`
+and `drivers.memory`), resolved on first use and once the app's config has
+loaded. It is the shared `memory` instance only when the config sets none of
+those. The shipped config sets them, so there `cache` and `memory` are two
+stores: a value written through one is not visible through the other.
+`cacheFromConfig(settings?)` builds the same choice explicitly;
+`resetConfiguredCache()` forgets it.
 `config/cache.ts` reads `REDIS_URL`, `REDIS_HOST`, `REDIS_PORT`,
 `REDIS_USERNAME`, `REDIS_PASSWORD` and `REDIS_DB`, as `config/queue.ts` does.
 

package/ai/skills/stacks-calendar/SKILL.md

@@ -38,11 +38,13 @@ title, required allDay and optional description/address/timezone; the root entry
 does not re-export that type. Infer a literal or read src/types.ts when extending
 the package.
 
-The older single-event generator has its own timezone/time-format rules and
-does not emit a VTIMEZONE block. Its UID derives from event timing/title, so
-editing those changes the UID. Do not promise subscription update semantics
-from a generated single-event link. Prefer the feed builder for stable records,
-escaping and folded lines.
+Single-event exports write a timed event as UTC instants (`...Z`), so a link
+means the same on every host; `timezone` only sets the zone Google's compose
+screen displays it in. All-day dates are the UTC calendar dates of from/to.
+The ICS body escapes and folds its text as the feed builder does. Its UID
+derives from the event's instants and title, so editing those changes the
+UID. Do not promise subscription update semantics from a generated
+single-event link; use the feed builder for stable records.
 
 ## Native subscribable feeds
 
@@ -59,13 +61,19 @@ control, even when the feed declares a suggested interval.
 
 ## Recurrence
 
-parseRRule(value) returns RecurrenceRule or null for unsupported frequency.
-expandRecurrence(rule, dtstart, windowStart, windowEnd) returns matching UTC
-start instants, capped defensively. Supported fields include DAILY/WEEKLY/
-MONTHLY/YEARLY, INTERVAL, COUNT, UNTIL, BYDAY and BYMONTHDAY. This is a subset;
-unknown fields are not a proof of full RFC conformance. Callers own timezone
-interpretation and DST policy. Calendar clients can expand a feed's raw rrule
-independently from the server subset.
+parseRRule(value) returns a RecurrenceRule, or null for any rule it cannot
+follow exactly: an unsupported frequency or part (BYMONTH, BYSETPOS, BYWEEKNO,
+BYYEARDAY, BYHOUR...), a combination RFC 5545 rules out or this subset does
+not cover, or a value it cannot read. Null means "do not expand this here",
+never "expanded without the part". expandRecurrence(rule, dtstart, windowStart,
+windowEnd) returns matching UTC start instants, capped at 1000.
+
+The subset: DAILY/WEEKLY/MONTHLY/YEARLY, INTERVAL, COUNT or UNTIL, WKST, BYDAY
+(a filter for DAILY and WEEKLY; within a month, `MO` is every Monday and `2TU`
+or `-1FR` an ordinal) and BYMONTHDAY for DAILY or MONTHLY (`-1` is the last
+day). Weeks start on WKST, Monday by default, as clients expand them. YEARLY
+repeats dtstart's date, skipping years without it (Feb 29). Callers own
+timezone interpretation and DST policy.
 
 ## Sources and evidence
 

package/ai/skills/stacks-chat/SKILL.md

@@ -95,7 +95,7 @@ abstract class BaseChatDriver implements ChatDriver {
 
 ```typescript
 interface ChatMessage {
-  to: string | string[]                // recipient (channel ID, user ID, etc.)
+  to?: string | string[]               // a bot token's channel or user ID; omit for a webhook
   from?: { id?: string, name?: string, avatar?: string }
   subject?: string                      // title for rich messages
   content?: string                      // plain text content
@@ -181,8 +181,14 @@ interface SlackAttachment {
 
 ### Slack Sending Modes
 
-1. **Webhook mode**: If `config.webhookUrl` is set, sends via `POST` to webhook URL. Payload includes `text`, `username`, `mrkdwn: true`. If `message.template` exists, builds Block Kit blocks.
-2. **Bot token mode**: If `config.botToken` is set, sends via Slack API `https://slack.com/api/chat.postMessage` with `Authorization: Bearer <token>`. Returns `ts` (timestamp) as message ID.
+1. **Webhook mode**: If `config.webhookUrl` is set, sends via `POST` to webhook URL. Payload includes `text`, `username`, `mrkdwn: true`. If `message.template` exists, builds Block Kit blocks. Needs no `message.to`.
+2. **Bot token mode**: If `config.botToken` is set, sends via Slack API `https://slack.com/api/chat.postMessage` with `Authorization: Bearer <token>`, to the channel in `message.to` (required). Returns `ts` (timestamp) as message ID.
+
+`send()` treats `content` as the plain text `ChatMessage` says it is: `&`, `<`
+and `>` are escaped (`escapeSlackText`), so `<!channel>` or a disguised
+`<url|label>` in user text arrives as literal text instead of pinging the
+channel or hiding a link. Plain URLs still link. `sendWebhook(url, text)` is
+raw, for Slack markup written on purpose.
 3. Throws `Error('Slack not configured: provide webhookUrl or botToken')` if neither is set.
 
 ### Direct Webhook Function
@@ -247,8 +253,15 @@ interface DiscordMessage {
 
 ### Discord Sending Modes
 
-1. **Webhook mode**: POST to `config.webhookUrl`. Handles `204` (empty success) responses. Returns `id` from response.
-2. **Bot token mode**: POST to `https://discord.com/api/v10/channels/{channelId}/messages` with `Authorization: Bot <token>`. Uses `message.to` as the channel ID.
+1. **Webhook mode**: POST to `config.webhookUrl`. Handles `204` (empty success) responses. Returns `id` from response. Needs no `message.to`.
+2. **Bot token mode**: POST to `https://discord.com/api/v10/channels/{channelId}/messages` with `Authorization: Bot <token>`. Uses `message.to` as the channel ID (required).
+
+Every payload carries `allowed_mentions`, by default `{ parse: ['users', 'roles'] }`
+(`DEFAULT_ALLOWED_MENTIONS`): people and roles named by ID ping, `@everyone`
+and `@here` in content never do. `sendWebhook()`'s `allowedMentions` replaces
+the default, and its camelCase options are sent under Discord's names
+(`avatar_url`, `allowed_mentions`) by `discordPayload()`. With a subject or
+template the body goes in the embed only, not also as `content`.
 
 ### Embed Building
 When `message.subject` or `message.template` is set, `buildEmbed()` creates an embed with:
@@ -457,10 +470,10 @@ All three drivers implement `sendWithRetry()`:
 
 Direct send returns ChatResult, with success false for a handled provider failure;
 inspect it before persisting sent state. Awaiting a send only proves the promise
-settled. Webhook configuration does not replace ChatMessage's to/content or
-template fields. The generic notify chat channel supplies a body-only shape and
-does not normalize every structured transport failure, so use this package's
-direct API when application behavior depends on valid chat delivery.
+settled. A webhook send needs no `to`; a bot-token send needs the channel in
+`to`. notify()'s chat channel sends the body as `content` and `chatRecipient`
+as `to`, through `recipient.chatDriver` or `config.notification.chat.default`,
+and a failed send is a failed NotifyResult.
 
 Settings resolve per send after app config readiness, with explicit configure
 overrides taking precedence. Retained request/config coverage lives under

package/ai/skills/stacks-database/SKILL.md

@@ -384,3 +384,13 @@ canonical numeric string value, so padded numeric inputs cannot reverse lock ord
 transaction handle and choose ownership filters; reads, writes and validation
 remain on that handle. This prevents opposite input order from creating a
 lock-order cycle during a transfer, merge or multi-item stock reservation.
+
+## Row leases for external operations
+
+`claimRowLease(table, ownerScope, { token, heartbeat }, ttlMs)` from
+`@stacksjs/database/runtime` claims model-owned nullable token and heartbeat
+columns atomically. It returns null when busy, or a lease with `renew()`,
+`release()`, `assertOwned()` and `commit(work)`. Renew periodically during I/O.
+Keep network work outside `commit`; commit locks and revalidates the token before
+writing one bounded batch. An expired worker cannot commit or release a successor.
+A lease's unique owner scope must include the resource binding where applicable.

package/ai/skills/stacks-desktop/SKILL.md

@@ -133,6 +133,13 @@ Write `app/Desktop/launcher.ts` and `build:desktop` compiles that instead, the
 same way anything under `app/` overrides its framework default. `DESKTOP_URL`
 and `APP_URL` then become optional, because the launcher decides what to open.
 
+Every launcher, the framework's or yours, compiles through
+`desktopLauncherCompileArgs()` to bytecode as an ES module: parsing the bundle
+was most of a launcher's start (Browser's agent reached its window host in
+379 ms as source, 146 ms as bytecode), for an executable about a quarter
+larger. Pass `bytecode: false` only to compare. Compile any helper binary of
+your own with the same function rather than hand-written `bun build` flags.
+
 ```ts
 // app/Desktop/launcher.ts - compiled to Contents/MacOS/<AppName>
 import { dirname, join } from 'node:path'

package/ai/skills/stacks-events/SKILL.md

@@ -26,10 +26,14 @@ Use the native event bus for process-local application and model events. Use
   downstream work determines the response.
 
 Payloadless events are supported by the emitter. Exact handlers receive the
-payload; wildcard and glob handlers receive `(eventName, payload)`.
+payload; wildcard and glob handlers receive `(eventName, payload)`. In a glob,
+`*` is any run of characters and `.` any one character (`*.created` matches
+`user:created`); every other character is literal.
 
 `emitter.on(name, handler, { priority })` sorts higher priorities first
-within each handler bucket. Equal priority preserves registration order.
+within each handler bucket. A priority belongs to that one registration, so
+one handler can run first for one event and last for another. Equal priority
+preserves registration order.
 Exact handlers run before glob buckets, then `*` handlers. Snapshotting keeps
 subscription changes during a dispatch from corrupting iteration.
 

package/ai/skills/stacks-i18n/SKILL.md

@@ -21,7 +21,7 @@ i18n/src/
 ├── translator.ts         # I18n class, global API (t, tc, te, tm)
 ├── formatter.ts          # Locale-aware formatting (dates, numbers, currency, lists)
 ├── loader.ts             # File-based translation loader (JSON, YAML, JS/TS)
-└── pluralization.ts      # CLDR plural rules for 25+ languages
+└── pluralization.ts      # CLDR plural rules, from the runtime's Intl.PluralRules
 ```
 
 ## Core Types
@@ -101,14 +101,13 @@ tc('items', 5)    // '5 items'
 
 ### Supported Languages
 
-| Rule | Languages |
-|------|-----------|
-| One/Other | en, de, nl, es, it, pt, sv, da, no, fi, el, he, hu, tr |
-| French (0-1=one) | fr |
-| No plural | zh, ja, ko, vi, th, id, ms |
-| One/Few/Many/Other | ru, uk, pl |
-| One/Few/Other | cs, sk |
-| Full (zero/one/two/few/many/other) | ar, cy |
+Every language the runtime's CLDR data covers, through `Intl.PluralRules`,
+for the full locale (`pt` counts 0 as `one`, `pt-PT` does not). A language it
+has no data for says `other` for every number; `hasPluralRule(locale)` tells
+you which. `addPluralRule(locale, rule)` overrides a language. The rules were
+a hand-written table of 33 languages until it turned out to leave out Catalan,
+Croatian, Serbian, Bulgarian and `nb` (they said `other` for 1) and to get
+Hebrew's `two` and Latvian's `zero` wrong.
 
 ```typescript
 import { getPluralCategory, addPluralRule, hasPluralRule } from '@stacksjs/i18n'
@@ -218,6 +217,6 @@ default:
 - **YAML parsed with Bun.YAML** - not a third-party parser
 - **Missing keys return the key itself** - not an error, not empty string
 - **Pluralization uses `|` separator** - not ICU MessageFormat
-- **CLDR rules are built-in** - no external data needed, 25+ languages hardcoded
+- **CLDR rules come from the runtime** - `Intl.PluralRules`, no data shipped and no table to fall out of date
 - **HTML escaping is opt-in** - `escapeValues: true` in config
 - **Formatting uses Intl APIs** - delegates to `Intl.DateTimeFormat`, `Intl.NumberFormat`, etc.