> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simplefunctions.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK and Agent hardening gap plan

> Current npm package hardening, alert creation idempotency, event identity limits, and execution boundaries.

Status: current implementation note.

This page records the practical boundary between SimpleFunctions SDK/Agent value and raw venue API use. It exists in `docs/rfcs/` and is linked from `docs/docs.json` under SDKs / Contracts.

## Package hardening

The CLI package is an executable and can bundle/minify with `ncc` and `terser`. The SDK and Agent SDK are libraries, so they intentionally keep typed ESM `dist/` modules instead of bundling everything into one opaque file. That preserves exports, declarations, tree-shaking, and consumer debugging.

Current publish guard:

* npm `files` only includes `dist/` and `README.md`
* package build removes stale `dist/` before compiling
* TypeScript build emits declarations but not source maps or declaration maps
* package-surface tests reject `src/`, tests, examples, scripts, `.env`, `.map`, `.tsbuildinfo`, secret-like filenames, and JS `sourceMappingURL`

This does not make a JavaScript library proprietary in the strong sense. It prevents accidental source, test, example, and source-map leakage while preserving a usable npm package.

## `alerts.create`

`alerts.create` is now a governed `user_write` surface over `POST /api/alert-rules`:

```ts theme={null}
await sf.alerts.create({
  watch: "KXFED-27APR-T3.50",
  type: "price_above",
  threshold: 60,
  idempotencyKey: "agent-run-123:fed-alert",
})
```

The API accepts `Idempotency-Key`, SDK `idempotencyKey`, or body `clientRequestId`. If none is provided, the API derives a deterministic semantic key from watched object, condition, severity, delivery channels, and webhook endpoint. It stores explicit caller idempotency keys separately from semantic keys on `alert_rules`, enforces DB unique indexes, checks existing rules before inserting, and re-reads the existing rule on unique-conflict retry races.

## Event surfaces

`events.search`, `event.inspect`, and `event.markets` remain deferred. The shortfall is not SDK wrapping. The API/domain model lacks a canonical SimpleFunctions event identity across Kalshi events, Polymarket events, calendar items, scan groups, research snapshots, and market groups.

Required before SDK/Agent exposure:

* a canonical event id or table with stable `eventKey`
* source evidence linking venue event ids, tickers/token ids, title normalization, close times, and outcome-set hash
* public read endpoints for search, inspect, and markets
* freshness and hallucination-risk rules in `contracts/sf-contract-map.draft.json`

Until then, SDK/Agent should use `markets.search`, `market.inspect`, `calendar.list`, `crossvenue.pairs`, and `query.ask` rather than pretending a unified event object exists.

## Execution boundary

`execution.place` is the SimpleFunctions governed execution path. It is useful for research-to-intent workflows, runtime orchestration, traceability, policy gates, and operator-controlled live execution.

Raw venue APIs remain the correct tool for high-frequency market making, latency-sensitive order management, venue-native order lifecycle handling, and strategies that need direct book subscription plus immediate replace/cancel loops.

The stack should maximize its strength here: SDK/Agent own context, contracts, policy, runtime readiness, intents, traces, monitoring, and ledger reconciliation. Venue-native execution engines own the hot path.