---
name: bijection-convex-tripwire
description: "Evaluate and integrate the Tripwire component with Bijection."
---

# Tripwire

Reads your Convex logs and tells you what needs you: wasted reads, real failures, abuse and Database I/O pace. Rules, arithmetic, one model call per window.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-tripwire
- Source: https://gitlab.com/ndivij2004/convex-tripwire
- npm: https://www.npmjs.com/package/convex-tripwire
- Directory: https://bijection.com/components/convex-tripwire

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-tripwire. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Tripwire. Follow the installation and configuration steps exactly.

# Tripwire

## Instructions

Tripwire is a Convex component that ingests your deployment's log stream, rolls it up into per-function window totals, and runs a combination of deterministic rules and a single model call per window to surface findings: excessive document reads, validator contract failures, error patterns, abuse signals, and Database I/O budget pace. Findings are written to a Convex table your app can subscribe to reactively. A CLI forwarder pipes logs from outside the deployment since components cannot subscribe to their own log stream.

### Installation

```bash
npm install convex-tripwire
```

Current npm version: `convex-tripwire@0.1.2`

## Use cases

- You want to catch functions scanning large numbers of documents without an index, wasting Database I/O budget, without manually querying logs
- You need to detect when a function's return value fails its own `returns` validator in production before users report it
- You want a reactive dashboard that surfaces new operational findings the moment each analysis window closes, without polling
- You need to track whether your deployment is on pace to exceed the free plan's 2 GB Database I/O monthly budget
- You want to distinguish real application defects from expected user errors like wrong passwords, using a model call that costs fractions of a cent per analysis window

## How it works

A long-running forwarder process runs `npx tripwire forward` outside the deployment, pipes log events to a `POST /tripwire/ingest` HTTP endpoint mounted by the component, and folds them into per-function per-minute totals before writing. The component accumulates those totals into rolling windows configured via `tripwire.configure(ctx, { windowMinutes, ioBudgetBytes, about, questions, alertUrl })`. Totals older than a week are deleted; a per-function moving average persists what they contributed.

At the end of each window a scheduled judge runs. Deterministic rules handle clear cases: a function whose return value fails its own validator is marked broken without a model call. For ambiguous cases, the component sends one request to the Jev model from TypeSafe AI, batching all questions for all active functions in the window into a single round trip. The model returns probabilities and catalog-index choices, never free text. Suggested fixes come from a fixed catalog in `src/core.ts`.

Findings are stored with kind (`waste`, `broken`, `regressed`, `abuse`, `quota`, `custom`), probability, urgency (0-3), and a suggested fix when the model's pick exceeds a confidence threshold. The `tripwire.findings(ctx)` query returns open findings reactively; `tripwire.resolve(ctx, id, 'fixed' | 'noise')` closes them. Noise findings are muted permanently per function. `tripwire.calibration(ctx)` reports per probability band how many of your closed findings were real, giving you empirical calibration data for the model's scores on your own workload.

Without a `JEV_API_KEY`, the component still runs the rule-based and arithmetic checks (contract violations, I/O pace) at no model cost. You can also try the same logic locally before installing anything by running `npx convex-tripwire check logs.jsonl` against a saved log file.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Tripwire is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-tripwire)
- [GitLab repository](https://gitlab.com/ndivij2004/convex-tripwire)
- [Live demo](https://gitlab.com/ndivij2004/convex-tripwire/-/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/convex-tripwire)
- [Convex documentation](https://docs.convex.dev)