@stacksjs/defaults 0.75.109 → 0.75.111

package/ai/skills/stacks-native/RECIPES.md

@@ -0,0 +1,108 @@
+# Native feature recipes
+
+Read the named subsystem skills for their complete contracts. Examples use
+explicit imports and supplied facts, not ambient declarations as runtime proof.
+
+## A model becomes schema and protected CRUD
+
+```ts
+// app/Models/WorkItem.ts
+import { defineModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+
+export default defineModel({
+  name: 'WorkItem',
+  table: 'work_items',
+  belongsTo: ['User'],
+  traits: {
+    useUuid: true,
+    useTimestamps: true,
+    useSoftDeletes: true,
+    useApi: {
+      uri: 'work-items',
+      routes: ['index', 'store', 'show', 'update', 'destroy'],
+      middleware: ['auth'],
+    },
+  },
+  attributes: {
+    title: {
+      fillable: true,
+      required: true,
+      validation: { rule: schema.string().min(1).max(120) },
+    },
+    done: {
+      fillable: true,
+      default: false,
+      validation: { rule: schema.boolean() },
+    },
+  },
+})
+```
+
+The relationship supplies the `user_id` foreign-key column. Generated CRUD
+recognizes user ownership and derives it from the authenticated user. A client
+cannot choose another owner by changing its request body. This is a user-owned
+resource, not a public catalog. Add a policy when per-row abilities need more
+rules than ownership alone.
+
+```sh
+./buddy generate:migrations
+# Review generated SQL and storage/framework/database/model-snapshot.<dialect>.json.
+./buddy generate:migrations
+# Confirm the second generation has no remaining diff.
+./buddy migrate
+./buddy generate
+```
+
+Generation refreshes registries and type declarations; it does not compile a
+new ORM class for this model. Import the app model explicitly when exact
+inference matters, or use its server global after boot has injected it.
+Test generated create/read/update/delete with real authenticated requests and
+another user's rows. Do not substitute a source-grep check for row isolation.
+
+## Extend instead of copying a built-in model
+
+```ts
+// app/Models/Order.ts
+import { extendModel } from '@stacksjs/orm'
+import { schema } from '@stacksjs/validation'
+import Order from '../../storage/framework/defaults/app/Models/commerce/Order'
+
+export default extendModel(Order, {
+  attributes: {
+    collectionNote: {
+      fillable: true,
+      validation: { rule: schema.string().max(200) },
+    },
+  },
+})
+```
+
+Inherited behavior follows upstream. Attribute entries merge by key; replacing
+one entry replaces that entry's settings, not just one field inside it. Review
+the resulting definition and generate the migration. Imported relations and
+the full model override semantics are documented in `stacks-models`.
+
+## Choose a custom action for behavior, not generic CRUD
+
+Use an Action for a domain transition, aggregation, provider operation, or a
+different authorization/response contract. Declare `validations` and let
+`handle(request)` infer the body rather than annotating it with a broad request
+type. `model` gives model-aware validation context; explicit action validations
+run automatically before `authorize`, `before`, and `handle`.
+
+Directly register the imported action through `createTypedRouter` when a typed
+consumer needs inferred input/output. String action paths remain lazy runtime
+references and do not provide the same response inference.
+
+## Atomic work and deferred side effects
+
+Use `transaction(async tx => ...)` and write through `tx` for every statement
+that belongs to the transaction. A `Model.create()` inside that callback uses
+the model executor; it is not automatically rebound to the callback handle.
+
+Queue dispatch is transaction-aware and can defer until commit. Read
+`stacks-queue` for `.afterCommit()`, `.withoutCommit()`, durable handler
+descriptors, idempotency, and JSON payload restrictions. Ordered event dispatch
+is different from awaiting listeners; use the result-bearing dispatch API
+when the calling operation needs listener outcomes.

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

@@ -0,0 +1,79 @@
+---
+name: stacks-native
+description: Use when planning or implementing a Stacks feature, choosing a native API, or checking which framework capability already solves a task. Covers the complete native package catalog, model-driven workflows, feature gates, driver evidence, and cross-package gotchas.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Native Stacks capabilities
+
+Start with the native feature that already owns the behavior. Read the selected
+subsystem skill before implementing its API. [CATALOG.md](CATALOG.md) maps every
+core package to task guidance and its current source entrypoint; browse the
+relevant section rather than loading the whole reference.
+
+## Choose a workflow
+
+| Need | Native workflow |
+|---|---|
+| Persist a new entity and expose CRUD | `stacks-models`, `stacks-migrations`, `stacks-orm`, `stacks-actions`, `stacks-router` |
+| Extend a built-in model without forking it | `extendModel`, then model-driven migration generation |
+| Typed requests and an inferred API client | `Action.validations`, directly registered actions, `createTypedRouter` and `createTypedClient` |
+| Authenticate or authorize rows | `stacks-auth`, model API ownership, middleware, policies and gates |
+| Render interactive pages and validate forms | `stacks-stx`, `stacks-composables`, `stacks-forms`, `stacks-ui` |
+| Queue work or run it later | `stacks-jobs`, `stacks-queue`, `stacks-scheduler` |
+| Send mail, notifications, SMS or push | `stacks-mail`, `stacks-email`, `stacks-notifications`, `stacks-sms`, `stacks-push` |
+| Publish CMS pages or run commerce | `stacks-cms`, `stacks-commerce`, `stacks-payments` |
+| Build sites, newsletters, charts or media | `stacks-sites`, `stacks-newsletter`, `stacks-charts`, `stacks-image`, `stacks-audio`, `stacks-video` |
+| Paginate, cache, search or store files | `stacks-pagination`, `stacks-cache`, `stacks-search-engine`, `stacks-storage` |
+| Enable an optional bundle or run an experiment | `stacks-features` for framework bundles, `stacks-feature-flags` for user-targeted flags |
+| Build, deploy or operate an app | `stacks-build`, `stacks-deploy`, `stacks-cloud`, `stacks-server`, `stacks-buddy` |
+
+## Model-first implementation
+
+Declare schema, validators, fillable fields, relationships, traits, and ownership
+in `app/Models/`. `defineModel()` produces the query surface immediately;
+`useApi` registers CRUD at runtime. It does not require generated ORM classes
+or generated action files. Add a custom Action only when the behavior differs
+from the native CRUD contract.
+
+Run `./buddy generate:migrations`, review the SQL and dialect snapshot, then
+run it again to confirm no further diff. Apply with `./buddy migrate`.
+Keep models, generated migrations, and the snapshot together in review.
+`migrate:fresh` destroys tables and is a separate development operation.
+
+See [RECIPES.md](RECIPES.md) for an end-to-end native tracer bullet and
+the cases that require an action, job, policy, or explicit route.
+
+## Important boundaries
+
+- `app/` overrides framework defaults. Use `extendModel` for additive model
+  changes; an ordinary override replaces the definition.
+- Generated CRUD defaults to authenticated routes. Ownership and policies
+  govern rows separately; unscoped writes may be withheld by the default
+  row-scoping policy. Do not weaken that policy to make an example work.
+- Transactional queries use the supplied `tx` handle. Model calls do not
+  automatically join that transaction's connection.
+- Optional bundles control model/migration/view selection. Route mounting has
+  its own registry and default-bundle selection; a package being installed
+  does not mean every route is public or mounted.
+- Browser declarations, stx eager bindings, demand-inline bindings, and
+  explicit imported composables are different surfaces. Read
+  `stacks-auto-imports` before using an unfamiliar bare name.
+- Use request-time subpath exports when available. Tooling barrels may load
+  migrations, config discovery, or native modules that a handler does not need.
+- A typed configuration or exported adapter is not proof of provider support.
+  [CAPABILITIES.md](CAPABILITIES.md) is generated from the driver evidence
+  registry, including partial and experimental limits.
+
+## Completion and freshness
+
+Use the subsystem's actual signatures and retained tests, and verify the
+requested behavior. Run pickier through buddy, relevant tests, and the proper
+typecheck. UI changes also complete the design preflight.
+
+Within the framework repository, the native catalog and driver reference are generated by
+`./buddy docs:native-skills`; `./buddy docs:native-skills:check` detects missing
+package guidance and stale references. That check establishes coverage and
+source freshness, not semantic correctness of every prose sentence.

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

@@ -0,0 +1,39 @@
+---
+name: stacks-newsletter
+description: Use when managing native subscriber lists, opt-in/unsubscribe, campaigns, scheduled delivery, variants, idempotency, or delivery usage. Covers @stacksjs/newsletter and the native marketing bundle.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Native newsletters and campaigns
+
+The newsletter facade exposes lists, campaigns, subscribe, unsubscribe and
+unsubscribeAll. This is the application delivery API; marketing copy and
+strategy skills do not replace its consent, state and failure contracts.
+
+## Lifecycle
+
+Use subscribe(email, options) and token-based unsubscribe rather than raw
+subscriber updates. Preserve one-click unsubscribe headers and suppression.
+List/campaign helpers own their schema and state transitions; direct column
+writes can bypass transition guards or schedule/idempotency behavior.
+
+Campaign delivery snapshots, dispatch keys and state conflict errors protect
+retries and concurrent queue requests. Scheduled work uses the package's actual
+transition and readiness checks. DeliveryVariant allocation and
+deliveryIdempotencyKey make repeated delivery explicit; usage limits and failure
+classification distinguish deferred, failed and suppressed outcomes.
+
+The transport uses configured email delivery and queue infrastructure. A queued
+campaign is not proof that a provider delivered every message. Persist results,
+handle webhooks according to the provider contract and respect opt-out state.
+Enable/install the marketing bundle and migrate its models before persistence.
+
+Prepare a draft or analysis within the request. Sending or scheduling a campaign
+requires authorization for its recipients and scope. Reuse existing authorization
+without asking again for each already-approved step.
+
+Source: core/newsletter/src/{newsletter,lists,subscriptions,campaigns,delivery,
+headers,sync,usage}.ts. Tests cover subscriptions, transition races, idempotency,
+delivery usage and failure behavior.

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

@@ -8,207 +8,122 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Notifications
 
-Multi-channel notification system with 5 channel types: email, SMS, chat, push, and database.
-
-## Key Paths
-- Core package: `storage/framework/core/notifications/src/`
-- Main entry: `storage/framework/core/notifications/src/index.ts`
-- Drivers: `storage/framework/core/notifications/src/drivers/`
-- Database driver: `storage/framework/core/notifications/src/drivers/database.ts`
-- Configuration: `config/notification.ts`
-- Notification model: `storage/framework/defaults/app/Models/Notification.ts`
-
-## Package Exports
-
-```typescript
-import {
-  useChat,
-  useEmail,
-  useSMS,
-  useDatabase,
-  useNotification,
-  notification,
-  DatabaseNotificationDriver,
-} from '@stacksjs/notifications'
-
-// Types
-import type { CreateNotificationOptions, DatabaseNotification } from '@stacksjs/notifications'
-```
-
-## Channel Factories
-
-Each factory returns the underlying driver module for that channel.
-
-```typescript
-// Email -- defaults to 'mailtrap', returns @stacksjs/email driver
-const emailDriver = useEmail('ses')
-const emailDriver = useEmail('sendgrid')
-const emailDriver = useEmail('mailgun')
-const emailDriver = useEmail('mailtrap')
-const emailDriver = useEmail('smtp')
-
-// SMS -- defaults to 'twilio', returns @stacksjs/sms driver
-const smsDriver = useSMS('twilio')
-const smsDriver = useSMS('vonage')
-
-// Chat -- defaults to 'slack', returns @stacksjs/chat driver
-const chatDriver = useChat('slack')
-const chatDriver = useChat('discord')
-const chatDriver = useChat('teams')
-
-// Database -- returns DatabaseNotificationDriver object
-const dbDriver = useDatabase()
-
-// Auto-detect by type -- dispatches to the correct factory
-const driver = useNotification('email', 'ses')
-const driver = useNotification('sms', 'twilio')
-const driver = useNotification('chat', 'slack')
-const driver = useNotification('database')
-
-// Default (uses config.default, falls back to 'email' + 'mailtrap')
-const driver = notification()
-```
-
-`useNotification()` reads `config/notification.ts` for the default type. If no default is set, it throws `'No default notification type set in config/notification.ts'`.
-
-The channel drivers are re-exports from their respective packages:
-- `email` driver: `@stacksjs/email`
-- `sms` driver: `@stacksjs/sms`
-- `chat` driver: `@stacksjs/chat`
-- `push` driver: `@stacksjs/push`
-
-## Database Notification Driver
-
-The `DatabaseNotificationDriver` provides CRUD operations for notifications stored in the `notifications` database table using Kysely query builder.
-
-### Send a Notification
-
-```typescript
-const db = useDatabase()
-
-const notification = await db.send({
-  userId: 1,
-  type: 'order.shipped',
-  data: { orderId: 42, trackingNumber: 'ABC123' },
-})
-// Returns the created DatabaseNotification with auto-generated id, timestamps
-```
-
-`send()` inserts a row into the `notifications` table with:
-- `user_id` from `options.userId`
-- `type` from `options.type`
-- `data` -- JSON.stringify'd from `options.data`
-- `read_at` set to `null`
-- `created_at` and `updated_at` set to current ISO timestamp
-
-### Query Notifications
-
-```typescript
-// All notifications for a user, ordered by created_at desc
-const all = await db.getUserNotifications(userId)
-
-// Only unread (where read_at is null), ordered by created_at desc
-const unread = await db.getUnreadNotifications(userId)
-
-// Count of unread notifications
-const count = await db.unreadCount(userId)
-```
-
-### Mark as Read
-
-```typescript
-// Mark a single notification as read (sets read_at to current timestamp)
-await db.markAsRead(notificationId)
-
-// Mark all unread notifications for a user as read
-await db.markAllAsRead(userId)
-```
-
-`markAllAsRead()` only updates rows where `read_at` is null.
-
-### Delete Notifications
-
-```typescript
-// Delete a single notification by ID
-await db.deleteNotification(notificationId)
-
-// Delete all notifications for a user
-await db.deleteAllNotifications(userId)
-```
-
-### DatabaseNotification Interface
-
-```typescript
-interface DatabaseNotification {
-  id: number
-  user_id: number
-  type: string          // e.g., 'order.shipped', 'payment.received'
-  data: string          // JSON stringified -- parse with JSON.parse() when reading
-  read_at: string | null  // ISO timestamp or null if unread
-  created_at: string    // ISO timestamp
-  updated_at: string | null  // ISO timestamp
-}
-```
-
-### CreateNotificationOptions Interface
-
-```typescript
-interface CreateNotificationOptions {
-  userId: number
-  type: string
-  data: Record<string, any>
+Use `notify` for application fan-out and the channel packages for their
+provider-specific APIs. The database inbox and delivery log are different data.
+
+## Application notification
+
+~~~ts
+import { notify } from '@stacksjs/notifications'
+
+const results = await notify(
+  { userId: 7, email: 'customer@example.com' },
+  { subject: 'Order shipped', body: 'Your order is on its way.', data: { orderId: 42 } },
+  ['email', 'database'],
+)
+for (const result of results) {
+  if (!result.success)
+    console.error(result.channel, result.error)
 }
-```
-
-## Notification Model Fields
-
-The Notification model at `storage/framework/defaults/app/Models/Notification.ts`
-maps the database notification inbox used by `DatabaseNotificationDriver`:
-
-- `user_id` comes from the `belongsTo: ['User']` relationship
-- `type` is an application event name such as `order.shipped`
-- `data` is a JSON string containing the notification payload
-- `readAt` maps to the nullable `read_at` column
-- `created_at` and `updated_at` come from `useTimestamps`
-
-The model uses `useApi` for its CRUD API and seeds 30 records by default. It
-must stay aligned with `notificationsTableSql()` in
-`storage/framework/core/database/src/notification-tables.ts`. Outbound
-transport attempts belong in a separate delivery-log model and table. Do not
-add email, SMS, or provider-specific delivery columns to the inbox model.
-
-## CLI Commands
-- `buddy make:notification [name]` -- scaffold a new notification
-
-## config/notification.ts
-
-```typescript
-import type { NotificationConfig } from '@stacksjs/types'
-
-export default {
-  default: 'email',
-} satisfies NotificationConfig
-```
-
-The `default` field controls which channel type `useNotification()` and `notification()` use when no type is specified. Valid values: `'email'`, `'sms'`, `'chat'`, `'database'`.
-
-## Architecture
-
-The notifications package is a thin aggregation layer. Each channel delegates to its own dedicated package:
-
-- **Email channel** (`useEmail`) -- re-exports `@stacksjs/email` (configured via `config/email.ts`)
-- **SMS channel** (`useSMS`) -- re-exports `@stacksjs/sms` (configured via `config/sms.ts`)
-- **Chat channel** (`useChat`) -- re-exports `@stacksjs/chat` (configured via `config/services.ts`)
-- **Push channel** -- re-exports `@stacksjs/push`
-- **Database channel** (`useDatabase`) -- built-in driver using `@stacksjs/database`
-
-The driver modules (`drivers/email.ts`, `drivers/sms.ts`, etc.) are single-line re-exports: `export * as email from '@stacksjs/email'`, `export * as sms from '@stacksjs/sms'`, etc.
-
-## Gotchas
-- The `data` field in database notifications is stored as a JSON string -- always `JSON.parse()` when reading
-- `read_at` is `null` for unread notifications -- use this to filter unread
-- The database driver uses Kysely's query builder with `as any` type casts on table/column names since the notifications table is dynamically referenced
-- Channel-specific configuration (SMTP credentials, Twilio keys, Slack tokens) lives in each channel's own config file, not in `config/notification.ts`
-- `useNotification()` throws if `config.default` is not set in `config/notification.ts`
-- The `notification()` function (without arguments) is a shorthand for `useNotification()` with defaults
-- The `nexmo` driver is a legacy alias for `vonage` in the SMS drivers index
+~~~
+
+`notify(recipient, payload, channels = ['email'], options = {})` returns
+`Promise<NotifyResult[]>`. Channels run with `Promise.allSettled` so one
+failure does not block another. Each result has `channel`, `success` and an
+optional `error`. A resolved call does not imply every channel succeeded.
+
+| Channel | Required recipient data | Native package |
+|---|---|---|
+| email | email | `@stacksjs/email` |
+| sms | phone | `@stacksjs/sms` |
+| chat | configured channel transport | `@stacksjs/chat` |
+| database | userId | database notification inbox |
+| push | pushTokens, a string or string array | `@stacksjs/push`, default Expo |
+| broadcast | broadcastChannel or userId | `@stacksjs/realtime` |
+
+Payload: `{ body, subject?, data?, action? }`. Email treats body as text and
+renders it through the framework layout. Use the exported `NotificationAction`
+type for an action link. The broadcast fallback is `private-user.{userId}` or
+public `notifications` when no user/channel is supplied. Its delivery is
+best-effort; a missing realtime server is not a durable notification queue.
+Read `stacks-chat` before choosing notify's chat channel: its generic body
+payload does not supply a provider's channel recipient or configure credentials.
+
+Current notify result mapping marks a fulfilled channel call successful. Email
+explicitly checks EmailResult, but SMS/chat/push structured failures and a
+broadcast result with delivered false are not all normalized into failed
+NotifyResult entries. For provider-confirmed status, use the direct channel API
+and inspect its structured result. The generic chat body also differs from
+ChatMessage's to/content contract; use direct chat send with a valid message.
+Delivery logs inherit this result mapping and are not final receipt evidence.
+
+## Preferences and delivery tracking
+
+When userId exists, `notify` filters disabled channels using
+`notification_preferences`. An absent preference allows the channel.
+`options.category` selects category-specific preferences. Global opt-outs still
+disable a channel even when a category opts in; omitting a category reads only
+global preferences.
+`options.ignorePreferences: true` explicitly bypasses the filter for a
+required transactional send. A lookup failure logs and sends the unfiltered
+list, so this is not a fail-closed consent boundary.
+
+Use `getNotificationPreferences`, `setNotificationPreference` and
+`bulkSetPreferences` with their exported types. Writes use a transaction and
+lock the user row; a bulk save is atomic across its whole preference matrix.
+SMS also consults persistent
+phone opt-outs unless ignorePreferences is true. Ordinary direct SMS sends have
+their own contract; see `stacks-sms`.
+
+Every effective channel outcome is recorded through
+`recordNotificationDelivery(makeDeliveryRecord(...))`. The source distinguishes
+missing optional schema compatibility from real persistence failures. Apply
+model-driven migrations before relying on persistence. Inspect channel results
+and transport results rather than assuming a delivery log is provider proof.
+
+## Channel factories
+
+- `useEmail(driver?)` returns a sendable transport. Without a driver it uses
+  the Mail singleton and `config/email.ts`. Unknown explicit drivers warn and
+  fall back to that singleton.
+- `useSMS(driver?)` and `useChat(driver?)` select their driver modules
+  (defaults Twilio and Slack); configure those packages before sending.
+- `useDatabase()` returns DatabaseNotificationDriver.
+- `usePush()` returns the push namespace, and `useBroadcast()` the broadcast driver.
+- `useNotification(type?, driver?)`/`notification()` select email, sms, chat
+  or database only. The default type comes from `config/notification.ts`,
+  falling back to email. Push/broadcast fan-out is through `notify` or their
+  dedicated factories, not this older type selector.
+
+## Database inbox
+
+~~~ts
+import { useDatabase } from '@stacksjs/notifications'
+
+const inbox = useDatabase()
+await inbox.send({ userId: 7, type: 'order.shipped', data: { orderId: 42 } })
+const unread = await inbox.getUnreadNotifications(7)
+const count = await inbox.unreadCount(7)
+await inbox.markAllAsRead(7)
+~~~
+
+Also available: `getUserNotifications(userId)`, `markAsRead(id)`,
+`deleteNotification(id)` and `deleteAllNotifications(userId)`. These
+id-only mutation helpers do not enforce ownership themselves; scope access in
+the application's authenticated action before calling them.
+
+Rows contain id, user_id, type, data (JSON string), read_at, created_at and
+updated_at. Parse data when reading; null read_at means unread. The native
+Notification model adds the User relation and timestamps; keep it aligned with
+`database/src/notification-tables.ts`. Provider attempts belong in the separate
+delivery log, not extra columns on the inbox.
+
+## Sources and evidence
+
+`storage/framework/core/notifications/src/index.ts` defines the real
+signatures. `preferences.ts`, `delivery.ts` and `drivers/database.ts`
+own their persistence; the query builder is bun-query-builder.
+`notifications.test.ts`, `delivery-tracking.test.ts`,
+`broadcast.test.ts` and `email-body.test.ts` cover retained behavior.
+For provider status, consult `config/src/capabilities.ts` and each channel
+skill; a constructed send request is not a live delivery assertion.

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

@@ -8,7 +8,8 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Object Utilities
 
-Type-safe object manipulation helpers. All functions are exported from a single file.
+Type-safe object manipulation helpers, with core functions in index.ts and
+additional transforms re-exported from transform.ts.
 
 ## Key Path
 - Core package: `storage/framework/core/objects/src/index.ts` (single file, all functions)
@@ -22,10 +23,10 @@ Type-safe object manipulation helpers. All functions are exported from a single
 
 ### objectMap -- Transform Object Key/Value Pairs
 ```typescript
-function objectMap<K extends string, V, NK = K, NV = V>(
+function objectMap<K extends string, V, NK extends PropertyKey = K, NV = V>(
   obj: Record<K, V>,
   fn: (key: K, value: V) => [NK, NV] | undefined,
-): Record<K, V>
+): Record<NK, NV>
 ```
 
 The callback receives `(key, value)` and must return either:
@@ -190,7 +191,20 @@ hasOwnProperty(null, 'a')          // false (no throw)
 hasOwnProperty(undefined, 'a')     // false (no throw)
 ```
 
-## Gotchas
+## Additional native transforms
+
+The root also exports `omit`, `pickBy`, `omitBy`, `mapValues`, `mapKeys`,
+`invert`, `isEmptyObject`, `getPath` and `setPath` from `transform.ts`.
+Use a path array such as `['items', 0, 'name']`, not an assumed dot-string
+parser. `getPath(source, path, fallback?)` reads a nested value;
+`setPath(source, path, value)` performs a persistent update by copying containers
+along the path and sharing unaffected siblings. Treat paths as application-owned
+inputs; this helper is not a path authorization boundary. Choose `objectPick` for key-based selection and
+`pickBy` for predicate selection. Read transform signatures for callback
+argument order; `objectMap`'s `(key, value)` is not a universal convention.
+Retained evidence: `core/objects/tests/transform.test.ts`.
+
+## Mutation and typing gotchas
 - `deepMerge` **mutates the target object** -- it does not create a new object. The return value is the same reference as `target`.
 - `clearUndefined` **mutates the input object** -- it deletes properties in place.
 - `objectPick` creates a NEW object -- original is not affected.