@johpaz/hive-sdk 0.4.3 → 0.4.5

package/docs/INDEX.md

@@ -0,0 +1,198 @@
+# Índice de Documentación — Hive SDK
+
+## Documentos de Usuario
+
+| Documento | Descripción |
+|-----------|-------------|
+| [README.md](../README.md) | Introducción, instalación, CLI, guía rápida |
+| [UPGRADING.md](./UPGRADING.md) | Migración a Bun 1.4.2 y TypeScript 7.0.2 |
+| [SECURITY-GUARDRAILS.md](./SECURITY-GUARDRAILS.md) | Límites de archivos, dependencias, runtime y controles de publicación |
+| [API-HOOKS.md](./API-HOOKS.md) | Engancharse al ciclo de vida: bloquear una tool, auditar, observar la compactación |
+| [API-ARTIFACTS.md](./API-ARTIFACTS.md) | Archivos fuera de la ventana de contexto, y su retención |
+| [API-RESILIENCE.md](./API-RESILIENCE.md) | Reintentos con backoff y circuit breakers |
+| [API-SESSIONS.md](./API-SESSIONS.md) | Sesiones por canal, historial, reanudación tras un corte |
+| [API-SERVICES.md](./API-SERVICES.md) | **La superficie para una UI** — CRUD de agentes, enjambres, skills, modelos, MCP, cron |
+| [API-AGENTS.md](./API-AGENTS.md) | createAgent, AgentLoop, Tool/Skill Selector, LLM Providers |
+| [API-DAG-SCHEDULER.md](./API-DAG-SCHEDULER.md) | DAGScheduler, TaskGraph, Estrategias, Presets |
+| [API-CRON.md](./API-CRON.md) | Tareas programadas: expresiones, zona horaria, misfires, motor sin dependencias |
+| [API-WORKERS-EVENTS.md](./API-WORKERS-EVENTS.md) | **Bun Workers**, createWorker, WorkerPool, AgentBus, EventBus, Canvas |
+| [API-TOOLS-SKILLS-CHANNELS.md](./API-TOOLS-SKILLS-CHANNELS.md) | Tools, Skills, MCP, Gateway, Channels, Tool Runtime, Storage |
+| [API-CONTEXT-COMPILER.md](./API-CONTEXT-COMPILER.md) | Context Compiler, Message History, Scratchpad, EthicsGuard, ACE |
+| [TEMPLATE-HIVE-APP.md](./TEMPLATE-HIVE-APP.md) | **Template hive-app** — estructura, opciones, personalización |
+| [HIVE-HARNESS.md](../docs/HIVE-HARNESS.md) | Posicionamiento: Hive como Agent Harness vertical |
+
+---
+
+## Guía de Inicio Rápido
+
+### 1. Crear una app harness completa
+
+```bash
+hives create-app my-hive
+cd my-hive
+bun install
+cp .env.example .env
+bun run dev
+```
+
+### 2. Crear Agente
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+
+const tool = defineTool({
+  name: "saludar",
+  description: "Saluda a alguien",
+  execute: async (args: { nombre: string }) => `¡Hola ${args.nombre}!`,
+});
+
+const agent = await createAgent({
+  name: "asistente",
+  provider: "openai",
+  model: "gpt-5.6-luna",
+  tools: [tool],
+});
+
+const respuesta = await agent.run("Saluda a Juan");
+```
+
+### 3. Crear un Bun Worker
+
+```typescript
+import { createWorker } from "@johpaz/hive-sdk";
+
+const worker = createWorker({
+  name: "researcher",
+  systemPrompt: "You are a research specialist...",
+});
+
+const result = await worker.run("Research quantum computing");
+worker.terminate();
+```
+
+### 4. Ejecutar un Swarm (DAG)
+
+```typescript
+import { DAGScheduler, TaskGraph } from "@johpaz/hive-sdk";
+
+const graph = new TaskGraph([
+  { id: "task1", agentId: "worker", name: "T1", taskDescription: "Tarea 1", deps: [] },
+  { id: "task2", agentId: "worker", name: "T2", taskDescription: "Tarea 2", deps: ["task1"] },
+]);
+
+const result = await new DAGScheduler().execute(graph);
+```
+
+### 5. Gateway + Canales
+
+```typescript
+import { startGateway, ChannelManager, TelegramChannel } from "@johpaz/hive-sdk";
+
+const server = await startGateway({ host: "127.0.0.1", port: 18790 });
+
+const channels = new ChannelManager(config);
+// channels.register("telegram", new TelegramChannel({ botToken: "..." }));
+```
+
+---
+
+## Estructura de Paquetes
+
+```
+packages/
+├── core/                   # @johpaz/hive-sdk
+│   └── src/
+│       ├── api/            # createAgent(), Agent interface
+│       ├── agent/          # AgentLoop, ContextCompiler, ConversationStore
+│       │   ├── providers/  # LLM providers (OpenAI, Anthropic, Gemini, Ollama)
+│       │   └── tool-selector.ts, skill-selector.ts, playbook-selector.ts (BM25 sobre HiveDB)
+│       ├── tools/          # 59 built-in tools + ToolRegistry + ToolExecutor
+│       ├── skills/         # SkillLoader, defineSkill()
+│       ├── swarm/          # DAGScheduler, TaskGraph, WorkerPool
+│       ├── workers/        # Bun Workers: createWorker, WorkerPool, agent.worker.ts
+│       ├── gateway/        # HTTP/WebSocket server (Bun.serve)
+│       ├── channels/       # Telegram, Discord, WhatsApp, Slack, Webchat
+│       ├── mcp/            # MCPClientManager + transports (SSE, WS, STDIO)
+│       ├── storage/        # HiveDB (colecciones + BM25)
+│       ├── canvas/         # CanvasManager + A2UI emitter
+│       ├── scheduler/      # CronScheduler + DAG execution
+│       ├── tool-runtime/   # Bun Worker pool para ejecución paralela de tools
+│       ├── ethics/         # EthicsGuard
+│       ├── memory/         # Scratchpad
+│       ├── config/         # loadConfig, loadEnv, getHiveDir
+│       ├── utils/          # logger, toon, crypto, retry
+│       └── index.ts        # Public API barrel
+│
+└── cli/                    # Hive CLI
+    └── src/
+        ├── index.ts        # Entry: hive <command>
+        └── commands/
+            ├── init.ts
+            ├── create-app.ts      # Generar app harness completa
+            ├── add-tool.ts        # Generar boilerplate de tool
+            ├── add-skill.ts       # Generar boilerplate de skill
+            ├── add-worker.ts      # Generar Bun Worker
+            ├── run.ts
+            ├── test.ts
+            └── trace.ts
+```
+
+---
+
+## Conceptos Clave
+
+### Agente
+Unidad de ejecución con configuración, contexto y ciclo de ejecución.
+
+### Tool
+Función invocable por el agente. Definida con `defineTool()`, seleccionada por búsqueda BM25.
+
+### Skill
+Composición de tools con triggers semánticos. Definida con `defineSkill()`.
+
+### Bun Worker
+Thread aislado que ejecuta un agente con system prompt propio. Creado con `createWorker()`.
+
+### WorkerPool
+Gestiona múltiples Bun Workers para ejecución paralela de tareas.
+
+### Swarm (DAG)
+Ejecución paralela de múltiples agentes con dependencias. Topological sort automático.
+
+### Gateway
+Servidor HTTP/WebSocket que expone el agente como API.
+
+### Channel
+Integración con plataformas de mensajería (Telegram, Discord, WhatsApp, Slack, Webchat).
+
+### MCP
+Model Context Protocol — herramientas externas via STDIO/SSE/WebSocket.
+
+---
+
+## Variables de Entorno
+
+```bash
+HIVE_HOME=~/.hive             # Raíz de datos (base, artefactos, config)
+HIVE_HOST=127.0.0.1           # Gateway host
+HIVE_PORT=18790               # Gateway port
+OPENAI_API_KEY=sk-...         # OpenAI
+ANTHROPIC_API_KEY=sk-ant-...  # Anthropic
+LOG_LEVEL=info                # debug | info | warn | error
+```
+
+---
+
+## Tests
+
+```bash
+# Tests unitarios (paralelo)
+bun test
+
+# Tests con timeout extendido
+bun test --timeout 60000
+```
+
+---
+
+*Documentación Hive SDK — ver `version` en package.json*

package/docs/SECURITY-GUARDRAILS.md

@@ -0,0 +1,87 @@
+# Guardrails de seguridad y compatibilidad
+
+Este documento enumera controles implementados y verificables. No sustituye la
+actualización de dependencias ni convierte un límite cooperativo en aislamiento
+de proceso.
+
+## Dependencias y cadena de suministro
+
+- `bun.lock` fija el grafo reproducible y CI instala con
+  `bun install --frozen-lockfile`.
+- `bun audit` es el control de aceptación para advisories conocidos. No existen
+  exclusiones generales ni overrides usados sólo para silenciar el auditor.
+- PDF.js está en 6.3.289 o posterior dentro de esa línea segura.
+- SheetJS CE se instala desde la distribución oficial 0.20.3; el paquete npm
+  abandonado en 0.18.5 no forma parte del grafo.
+- Baileys está fijado exactamente en `7.0.0-rc14` para evitar retroceder a una
+  release candidate vulnerable.
+- PptxGenJS 4.0.1 se conserva como artefacto ESM vendorizado, con licencia,
+  procedencia y SHA-256. No se instala su dependencia muerta `image-size`.
+
+Toda actualización del artefacto PPTX debe verificar su origen y hash, ejecutar
+la prueba OOXML y volver a ejecutar el audit.
+
+## Archivos PDF
+
+Antes de leer un PDF, `office_leer_pdf` exige un archivo regular y limita el
+tamaño a **25 MiB**. El parser se configura con:
+
+```typescript
+enableScripting: false
+isEvalSupported: false
+```
+
+Cada solicitud puede extraer como máximo **200 páginas**. Los rangos deben usar
+enteros válidos y el lector comprueba un deadline de **30 segundos** entre
+páginas. `loadingTask.destroy()` se ejecuta siempre al terminar.
+
+El deadline es cooperativo: no puede interrumpir una operación interna de
+PDF.js que bloquee antes de devolver el control. El límite de bytes, el límite
+de páginas y la versión corregida de la dependencia son los controles primarios.
+
+## Archivos XLSX
+
+`office_leer_xlsx` exige un archivo regular y rechaza entradas mayores a
+**15 MiB** antes de cargarlas. El workbook acepta como máximo **50 hojas** y se
+leen como máximo **10.000 filas por hoja**; `sheetRows` limita además el trabajo
+del parser. Hay un deadline cooperativo de **30 segundos** comprobado entre
+hojas.
+
+SheetJS se carga bajo demanda. Si la distribución oficial no está instalada, la
+herramienta devuelve un error operativo explícito en vez de propagar un
+`Cannot find module` ambiguo.
+
+## Escritura PPTX
+
+`office_escribir_pptx` expone sólo portada, texto, viñetas y notas. No acepta
+rutas, buffers ni datos de imágenes. El artefacto vendorizado importa `jszip`,
+pero no `image-size`; su hash y procedimiento de actualización están en
+`packages/core/src/vendor/pptxgenjs/README.md`.
+
+Agregar `addImage`, fondos con imágenes o cualquier entrada binaria invalida
+este guardrail y requiere una revisión de seguridad antes de publicarse.
+
+## Runtime, tipos y transportes
+
+- Bun **>=1.4.2** está declarado en `engines`; CI usa exactamente 1.4.2.
+- TypeScript **7.0.2** está fijado para hacer reproducible el typecheck.
+- SSE acepta sólo el contrato de stream que consume (`read`) y no depende de la
+  extensión Bun `readMany`.
+- WebSocket delimita `Bun.WebSocketOptions` sin desactivar el chequeo de tipos;
+  conserva reintentos limitados y distingue cierres intencionales.
+- Audio usa `Uint8Array<ArrayBuffer>` antes de construir `Blob`, evitando
+  compartir memoria respaldada por `SharedArrayBuffer` con la petición.
+
+## Verificación antes de publicar
+
+```bash
+bun --version
+bun install --frozen-lockfile
+bun run typecheck
+bun test
+bun audit
+git diff --check
+```
+
+El resultado aceptable es Bun 1.4.2 o posterior, typecheck y pruebas sin fallos,
+audit sin vulnerabilidades y un diff sin errores de whitespace.

package/docs/TEMPLATE-HIVE-APP.md

@@ -0,0 +1,360 @@
+# Template `hive-app` — Documentación Completa
+
+El template `hive-app` genera una **aplicación harness completa** lista para ejecutar. Incluye gateway HTTP/WebSocket, agente coordinador, configuración de canales, base de datos HiveDB, y deployment con Docker.
+
+---
+
+## Generar una app
+
+```bash
+hives create-app my-hive
+```
+
+Esto crea el directorio `my-hive/` con la estructura completa.
+
+---
+
+## Estructura generada
+
+```
+my-hive/
+├── package.json              # Dependencias y scripts
+├── hive.config.ts            # Configuración del harness
+├── docker-compose.yml        # Deployment con Docker
+├── .env.example              # Variables de entorno de ejemplo
+├── .gitignore                # Archivos ignorados por git
+└── src/
+    ├── main.ts               # Entry point — arranca gateway + agente
+    └── agents/
+        └── coordinator.ts    # Definición del agente coordinador
+```
+
+---
+
+## Archivos y opciones
+
+### `package.json`
+
+```json
+{
+  "name": "my-hive",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "start": "bun run src/main.ts",
+    "build": "bun build src/main.ts --outdir dist --target bun"
+  },
+  "dependencies": {
+    "@johpaz/hive-sdk": "latest"
+  }
+}
+```
+
+| Script | Comando | Descripción |
+|--------|---------|-------------|
+| `dev` | `bun run src/main.ts` | Ejecutar en desarrollo |
+| `start` | `bun run src/main.ts` | Ejecutar en producción |
+| `build` | `bun build ...` | Compilar a `dist/` |
+
+---
+
+### `hive.config.ts`
+
+Configuración central del harness.
+
+```typescript
+import type { Config } from "@johpaz/hive-sdk";
+
+export default {
+  name: "my-hive",
+  gateway: {
+    host: process.env.HIVE_HOST ?? "127.0.0.1",
+    port: Number(process.env.HIVE_PORT ?? 18790),
+  },
+  channels: {
+    webchat: { enabled: true },    // Siempre habilitado
+    telegram: { enabled: false },  // Requiere TELEGRAM_BOT_TOKEN
+    discord: { enabled: false },   // Requiere DISCORD_BOT_TOKEN
+    whatsapp: { enabled: false },  // Requiere configuración adicional
+    slack: { enabled: false },     // Requiere SLACK_BOT_TOKEN
+  },
+  database: {
+    path: process.env.HIVE_DATA_DIR ?? "./data/hive.db",
+  },
+} satisfies Config;
+```
+
+#### Opciones de configuración
+
+| Opción | Tipo | Default | Descripción |
+|--------|------|---------|-------------|
+| `name` | `string` | `"my-hive"` | Nombre de la aplicación |
+| `gateway.host` | `string` | `"127.0.0.1"` | Host del gateway |
+| `gateway.port` | `number` | `18790` | Puerto del gateway |
+| `channels.webchat.enabled` | `boolean` | `true` | Canal webchat integrado |
+| `channels.telegram.enabled` | `boolean` | `false` | Bot de Telegram |
+| `channels.discord.enabled` | `boolean` | `false` | Bot de Discord |
+| `channels.whatsapp.enabled` | `boolean` | `false` | Bot de WhatsApp |
+| `channels.slack.enabled` | `boolean` | `false` | Bot de Slack |
+| `database.path` | `string` | `"./data/hive"` | Ruta de la base de datos HiveDB |
+
+---
+
+### `src/main.ts`
+
+Entry point de la aplicación. Realiza:
+
+1. Inicializa la base de datos (`ensureHiveDb`, que además siembra el catálogo)
+2. Crea el agente coordinador (`createAgent`)
+3. Inicializa el ChannelManager
+4. Arranca el gateway (`startGateway`)
+5. Maneja shutdown graceful (`SIGINT`)
+
+```typescript
+import {
+  createAgent,
+  startGateway,
+  ensureHiveDb,
+  ChannelManager,
+  logger,
+} from "@johpaz/hive-sdk";
+import config from "../hive.config.ts";
+
+const log = logger.child("app");
+
+async function main() {
+  log.info(`Starting my-hive...`);
+
+  await ensureHiveDb();
+
+  const agent = await createAgent({
+    name: "coordinator",
+    provider: "openai",
+    model: "gpt-5.6-luna",
+    systemPrompt: "You are a helpful AI assistant...",
+  });
+
+  const channelManager = new ChannelManager();
+  // TODO: configure channels from hive.config.ts
+
+  const gateway = await startGateway({
+    host: config.gateway?.host,
+    port: config.gateway?.port,
+    agentId: "coordinator",
+  });
+
+  log.info(`my-hive is running at http://${gateway.hostname}:${gateway.port}`);
+}
+
+main().catch((err) => {
+  log.error("Fatal error:", err);
+  process.exit(1);
+});
+```
+
+#### Personalizar el agente
+
+Puedes cambiar el `provider`, `model`, y `systemPrompt`:
+
+```typescript
+const agent = await createAgent({
+  name: "coordinator",
+  provider: "anthropic",        // cualquiera de los 16 del catálogo
+  model: "claude-3-5-sonnet-20241022",
+  systemPrompt: "Tu system prompt personalizado...",
+});
+```
+
+#### Añadir tools al agente
+
+```typescript
+import { defineTool } from "@johpaz/hive-sdk";
+
+const searchTool = defineTool({
+  name: "search",
+  description: "Search the web",
+  execute: async (args: { query: string }) => {
+    // Implementation
+    return { results: [] };
+  },
+});
+
+const agent = await createAgent({
+  name: "coordinator",
+  provider: "openai",
+  model: "gpt-5.6-luna",
+  tools: [searchTool],
+});
+```
+
+---
+
+### `src/agents/coordinator.ts`
+
+Definición standalone del agente coordinador. Puedes importarlo desde `main.ts` o usarlo directamente.
+
+```typescript
+import { createAgent } from "@johpaz/hive-sdk";
+
+export const coordinatorAgent = await createAgent({
+  name: "coordinator",
+  provider: "openai",
+  model: "gpt-5.6-luna",
+  systemPrompt: "You are the coordinator agent...",
+});
+```
+
+---
+
+### `docker-compose.yml`
+
+Deployment containerizado.
+
+```yaml
+services:
+  app:
+    image: oven/bun:latest
+    working_dir: /app
+    volumes:
+      - .:/app
+      - hive-data:/app/data
+    ports:
+      - "${HIVE_PORT:-18790}:18790"
+    environment:
+      - HIVE_HOST=0.0.0.0
+      - HIVE_PORT=18790
+      - HIVE_DATA_DIR=/app/data
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+    command: ["bun", "run", "src/main.ts"]
+    restart: unless-stopped
+
+volumes:
+  hive-data:
+```
+
+#### Deployment
+
+```bash
+# Copiar variables de entorno
+cp .env.example .env
+# Editar .env con tus API keys
+
+# Levantar con Docker
+docker compose up -d
+
+# Ver logs
+docker compose logs -f
+```
+
+---
+
+### `.env.example`
+
+Variables de entorno disponibles:
+
+```bash
+# Hive Harness Configuration
+HIVE_HOST=127.0.0.1
+HIVE_PORT=18790
+HIVE_DATA_DIR=./data
+
+# LLM Providers
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+
+# Channels (enable as needed)
+TELEGRAM_BOT_TOKEN=
+DISCORD_BOT_TOKEN=
+SLACK_BOT_TOKEN=
+
+# Logging
+LOG_LEVEL=info
+```
+
+| Variable | Requerida | Descripción |
+|----------|-----------|-------------|
+| `HIVE_HOST` | No | Host del gateway |
+| `HIVE_PORT` | No | Puerto del gateway |
+| `HIVE_HOME` | No | Directorio de datos (HiveDB en `<HIVE_HOME>/data`) |
+| `OPENAI_API_KEY` | Sí* | API key de OpenAI |
+| `ANTHROPIC_API_KEY` | Sí* | API key de Anthropic |
+| `GOOGLE_API_KEY` | Sí* | API key de Gemini |
+| `TELEGRAM_BOT_TOKEN` | No | Token del bot de Telegram |
+| `DISCORD_BOT_TOKEN` | No | Token del bot de Discord |
+| `SLACK_BOT_TOKEN` | No | Token del bot de Slack |
+| `LOG_LEVEL` | No | `debug` \| `info` \| `warn` \| `error` |
+
+\* Al menos una API key de LLM es requerida.
+
+---
+
+## Personalización avanzada
+
+### Añadir canales
+
+```typescript
+// src/main.ts
+import { TelegramChannel, DiscordChannel } from "@johpaz/hive-sdk";
+
+const channelManager = new ChannelManager(config);
+
+if (config.channels.telegram.enabled) {
+  channelManager.register("telegram", new TelegramChannel({
+    botToken: process.env.TELEGRAM_BOT_TOKEN!,
+  }));
+}
+
+if (config.channels.discord.enabled) {
+  channelManager.register("discord", new DiscordChannel({
+    botToken: process.env.DISCORD_BOT_TOKEN!,
+  }));
+}
+
+await channelManager.initialize();
+```
+
+### Añadir workers especializados
+
+```bash
+cd my-hive
+hives add-worker researcher
+hives add-worker coder
+```
+
+Esto genera `src/workers/researcher.worker.ts` y `src/workers/coder.worker.ts`.
+
+### Añadir tools
+
+```bash
+cd my-hive
+hives add-tool search-docs
+```
+
+Genera `src/tools/search-docs.ts`.
+
+### Añadir skills
+
+```bash
+cd my-hive
+hives add-skill onboarding
+```
+
+Genera `src/skills/onboarding.ts`.
+
+---
+
+## Tests del template
+
+El template incluye tests para verificar que la estructura se genera correctamente.
+
+```bash
+cd my-hive
+bun test
+```
+
+---
+
+*Documentación Hive SDK — ver `version` en package.json*

package/docs/UPGRADING.md

@@ -0,0 +1,65 @@
+# Actualización a Bun 1.4.2 y TypeScript 7
+
+Hive SDK requiere **Bun 1.4.2 o posterior** y usa **TypeScript 7.0.2** para
+desarrollo y verificación. El SDK se publica como TypeScript, por lo que estas
+versiones también importan al compilar una aplicación consumidora.
+
+## Actualizar un checkout del SDK
+
+```bash
+bun --version                 # debe ser 1.4.2 o posterior
+bun install --frozen-lockfile
+bun run typecheck
+bun test
+bun audit
+```
+
+El `package.json` raíz fija TypeScript 7.0.2 para que CI y desarrollo resuelvan
+el mismo compilador. `@hive/core` acepta versiones compatibles desde 7.0.2
+mediante su peer `^7.0.2`, porque publica sus fuentes. `@types/bun` permanece en
+1.4.1: es la versión publicada de tipos correspondiente disponible al cerrar
+esta migración.
+
+## Actualizar una aplicación consumidora
+
+1. Instala Bun 1.4.2 o una versión posterior compatible.
+2. Actualiza el compilador de la aplicación:
+
+   ```bash
+   bun add --dev typescript@7.0.2 @types/bun@^1.4.1
+   ```
+
+3. Regenera la instalación con `bun install` y ejecuta el typecheck propio.
+4. No añadas `skipLibCheck` para ocultar errores nuevos del SDK. Hive ya lo usa
+   internamente para declaraciones de terceros, pero su código fuente debe
+   seguir compilando completo.
+
+## Cambios de tipos relevantes
+
+TypeScript 7 distingue el respaldo de memoria de los typed arrays. Un
+`Uint8Array<ArrayBufferLike>` podría usar `SharedArrayBuffer` y ya no es válido
+automáticamente como `BlobPart`; Hive conserva bytes respaldados por
+`ArrayBuffer` al construir audio para APIs de transcripción.
+
+Con `DOM` y los tipos de Bun activos simultáneamente también aparecen dos APIs
+con definiciones superpuestas:
+
+- `ReadableStreamDefaultReader` de Bun añade `readMany()`, aunque el transporte
+  SSE sólo necesita `read()`. El transporte depende de ese contrato mínimo.
+- El constructor DOM de `WebSocket` sólo conoce subprotocolos; Bun permite
+  `Bun.WebSocketOptions`, incluidos headers. El transporte delimita esa
+  extensión en un tipo de constructor local.
+
+Estos adaptadores están en la frontera con el runtime. No deben reemplazarse por
+`any`, `@ts-ignore` o `@ts-expect-error`: hacerlo convertiría una incompatibilidad
+real de plataforma en un falso resultado verde.
+
+## Compatibilidad y CI
+
+Los workflows fijan Bun 1.4.2, instalan con `--frozen-lockfile`, ejecutan el
+typecheck de TypeScript 7 y la suite. También generan una aplicación nueva y la
+compilan enlazada contra el SDK del commit, no contra la última versión de npm.
+
+Antes de elevar Bun o TypeScript otra vez, actualiza primero CI, reproduce el
+typecheck localmente y documenta cualquier cambio de tipos observable para los
+consumidores.