§ DOCUMENTATION

Enforcement Bypasses

When an SDK cannot get an enforcement decision it can let the action proceed. Execlave records every such ungoverned stretch in your audit log and carries it in the signed compliance report — so “no record” never reads as “fully governed”.

§ 01

What a bypass is

Policies are evaluated by the platform. The SDK is a separate failure domain: if enforcePolicy() (JavaScript) or enforce_policy() (Python) cannot obtain a decision, the SDK's own settings decide what happens — not a policy's failureMode. Under the default fail_open the action proceeds. That is a bypass: a call that ran with no server-side enforcement decision.

Situation	Setting	Default	What happens
Network error, 5xx, or an open circuit breaker	`enforcementOnOutage`	`fail_open`	The call returns allowed: true with a source of fail_open_network_error, fail_open_server_error, or fail_open_circuit_breaker. Under fail_closed it throws EnforcementUnavailableError.
Plan quota exhausted (HTTP 402)	`planLimitBehavior`	`fail_open`	The call returns allowed: true with a source of fail_open_plan_limit. Under fail_closed it throws PlanLimitExceededError.

A quota bypass is a governance gap even though the cause is commercial rather than an outage, and it is the one most likely to occur in normal operation. It is recorded exactly like the others.

§ 02

How bypasses are recorded

From SDK 1.8.0, both the JavaScript and Python SDKs report bypasses to Execlave, where each is written to your organization's append-only, hash-chained audit log as enforcement.bypassed.

A record covers a window, not a single call: consecutive bypasses for the same agent and reason are coalesced. A window closes when the agent next receives a governed decision, after 60 seconds without a bypass, or after 15 minutes. A two-hour outage is therefore a handful of records rather than thousands, and a record never changes once written.

Reports are delivered from a background timer with retry and backoff. They never run inside an enforcement call, and the endpoint is not subject to your plan limit — so a bypass caused by an exhausted quota can still be reported.

§ 03

Reading the record

List them from the audit log with the action filter, bounded by startDate and endDate:

curl "https://api.execlave.com/api/v1/audit-logs?action=enforcement.bypassed&startDate=2026-09-01&endDate=2026-09-30" \  -H "Authorization: Bearer $EXECLAVE_API_KEY"

Each entry has resource type enforcement_window, and the window's id as its resource id:

{  "action": "enforcement.bypassed",  "resourceType": "enforcement_window",  "resourceId": "6f1c2a9e-3b7d-4c55-9a1e-0d2f8b6c7e41",  "metadata": {    "agentId": "support-bot",    "agentResolved": true,    "resolvedAgentId": "0b8e7c1a-…",    "reason": "network_error",    "source": "fail_open_network_error",    "count": 412,    "message": "connect ECONNREFUSED",    "clientReported": {      "firstAt": "2026-09-10T12:00:03.114Z",      "lastAt": "2026-09-10T12:41:57.902Z",      "sentAt": "2026-09-10T12:43:02.771Z"    },    "serverObserved": {      "receivedAt": "2026-09-10T12:43:02.845Z",      "skewMs": 74,      "clockSkewSuspect": false    },    "sdk": { "name": "@execlave/sdk", "language": "js", "version": "1.8.0" }  }}

Field	Meaning
`agentId`	The agent id exactly as the SDK reported it. agentResolved says whether it maps to an agent in your organization; an unknown id is still recorded.
`reason`	network_error, server_error, circuit_breaker_open, or plan_limit_exceeded. source is the matching fail_open_* string returned to the caller.
`count`	How many calls the window covers — calls that ran without a server enforcement decision.
`clientReported`	When the window began and ended, and when it was sent — as the SDK’s own clock claimed. Attested by the API key, not measured by the platform.
`serverObserved`	When the platform received the report (receivedAt), the difference from the SDK’s clock (skewMs), and clockSkewSuspect, which is true when they differ by more than five minutes. A skewed clock never causes a report to be rejected.
`sdk`	The reporting SDK’s name, language, and version.

Reporting loss is recorded too. If an outage outlasts an SDK's in-memory buffer (500 closed windows), the oldest windows are dropped and the next successful report adds an enforcement.bypass_reports_dropped entry with droppedWindows and droppedBypasses. The record says “N bypasses were not reported” instead of staying silent.

§ 04

In the signed compliance report

A report that states enforcement counts and says nothing about the calls that never reached enforcement invites the reader to assume every call was governed. Compliance reports therefore carry an enforcementBypasses section inside the signed body: altering it invalidates the signature. It is also rendered in the HTML and PDF exports as “Enforcement Bypasses (Ungoverned Execution)”, and the monitoring control cites it next to the enforcement count it qualifies.

"enforcementBypasses": {  "windows": 3,  "bypassedCalls": 461,  "agents": 2,  "byReason": {    "circuit_breaker_open": { "windows": 0, "bypassedCalls": 0 },    "network_error":        { "windows": 2, "bypassedCalls": 452 },    "server_error":         { "windows": 0, "bypassedCalls": 0 },    "plan_limit_exceeded":  { "windows": 1, "bypassedCalls": 9 }  },  "clockSkewSuspectWindows": 0,  "unresolvedAgentWindows": 0,  "reportingLoss": { "notices": 0, "droppedWindows": 0, "droppedBypasses": 0 },  "items": [ /* the largest windows, up to 200 */ ],  "itemsTruncated": false,  "scope": "organization",  "windowFrom": "2026-09-01T00:00:00.000Z",  "windowTo": "2026-09-30T23:59:59.999Z",  "limitations": [ /* why an empty figure is not proof of full governance */ ]}

Same period and scope as the rest of the report. Windows are attributed to the period in which the platform received them, not the SDK's clock. An agent-scoped report includes only windows resolved to those agents; windows whose agent id did not resolve are excluded and counted in unresolvedAgentWindows rather than dropped silently. Reporting loss is shown in full, because it qualifies every figure.
Not a verdict. The monitoring control's met / partial / not-met status is not changed by bypasses. Turning a count into a status needs a threshold you choose.
An empty figure is never presented as clean. With no windows the report says “None reported” and explains that is not the same as none occurring. A report saved before this section existed says the section is not included, never “none”.
A failed read fails the report. If the bypass records cannot be read, generation fails instead of omitting the section.

§ 05

Configuration

Reporting is on by default, because the evidence is the point. To keep only the local callback and send nothing to Execlave, set reportBypassesToPlatform: false (JavaScript) or report_bypasses_to_platform=False (Python). The callback fires once per bypassed call either way.

// JavaScriptconst exe = new Execlave({  apiKey: process.env.EXECLAVE_API_KEY!,  enforcementOnOutage: 'fail_open',       // or 'fail_closed' — refuse instead of proceeding  planLimitBehavior: 'fail_open',  onEnforcementBypassed: (e) => alert(e), // local, once per bypassed call  reportBypassesToPlatform: true,         // default (1.8.0+): also record in your audit log}); # Pythonexe = Execlave(    api_key=os.environ["EXECLAVE_API_KEY"],    enforcement_on_outage="fail_open",    plan_limit_behavior="fail_open",    on_enforcement_bypassed=alert,    report_bypasses_to_platform=True,    # default (1.8.0+))

Setting (JS / Python)	Values	Default
`enforcementOnOutage`	fail_open \| fail_closed	`fail_open`
`planLimitBehavior`	fail_open \| fail_closed	`fail_open`
`reportBypassesToPlatform`	true \| false	`true`

§ 06

What this does not cover

A crash during an outage loses the unsent buffer. Nothing is spooled to disk; what had not been delivered is not reported.
A window is reported only after it closes. A stretch still open is not yet visible. On a clean shutdown, open windows are closed and one bounded attempt is made to send them.
Delivery needs the platform to be reachable again. During an outage records queue in memory and are sent once contact returns.
fail_closed produces no records. Nothing was bypassed; the call was refused.
SDKs older than 1.8.0 report nothing. They emit only the local callback, so an absent record from an older SDK is not evidence that its calls were governed.
Timestamps inside clientReported are the SDK's claim. Compare with serverObserved.
The message can contain an internal host name or address from the underlying network error. It is truncated to 500 characters and stays inside your own organization's audit log.

§ 07

Frequently asked questions

If a report shows no bypass windows, were all my calls governed?

Not necessarily. Bypass records are reported by the SDK, so an empty result means none were reported — not that none occurred. Only SDK versions 1.8.0 and later report, reporting can be switched off per client, and a process that crashed before delivering its buffer reports nothing for that stretch. The report says this in its own text and carries the same caveats in the signed JSON, so an empty figure is never presented as a clean one.

Does a bypass mean the action was unsafe?

It means the action ran without a server-side enforcement decision: policies were not evaluated for that call. Whether it was safe depends on what the agent did. That is exactly why the stretch is recorded — so you can look at what the agent did during it. If an action must never run ungoverned, set enforcementOnOutage to fail_closed for that client and the call is refused instead.

Can reporting slow down or break my agent?

No. Recording a bypass is an in-memory operation. Delivery happens from a background timer or thread with retry and backoff and never inside an enforcement call, so a slow or unreachable reporting endpoint cannot delay or fail one. On shutdown the SDK makes one attempt bounded to about three seconds.

Can I turn it off?

Yes. Set reportBypassesToPlatform: false in the JavaScript SDK or report_bypasses_to_platform=False in the Python SDK. The local onEnforcementBypassed / on_enforcement_bypassed callback is unaffected and still fires once per bypassed call. With reporting off, your audit log and compliance reports have no record of that client’s ungoverned stretches.

Why does the compliance report not mark the monitoring control as failed when there are bypasses?

Because turning a count into a verdict needs a threshold, and the right threshold — one bypassed call, one percent of traffic, any bypass on a regulated agent — is your decision, not the report’s. The report states the figures next to the enforcement counts they qualify, in the signed body and in the human-readable export, and leaves the control status as it was.