Limren Docs.

Limren controls the final point at which a proposed action can change an external system, then verifies the observed result.

Why a decision is not permission to execute

An agent can reason, plan, and propose. Limren becomes relevant when that proposal is about to change an external system. A positive decision made earlier is not permanent permission to execute later.

How to use these docs

If you are new to Limren, read Core lifecycle and Commit boundary, then use the Playground. If you are evaluating implementation behavior, move to Action envelope, Preconditions & conflict, and the Reference section.

Core lifecycle.

A proposal is bound to current facts, decided, checked again at commit, and verified against the resulting state.

Lifecycle overview

Intent

An intent is the requested state change: who is acting, what should change, which target is affected, and what authority supports the request.

Bind

Limren binds the decision to the exact target, payload, authority, evidence, and dependencies it evaluated. If any of those values change, the old decision cannot silently authorize the new action.

Validate and decide

Limren checks the action against current authority, policy, state, constraints, and dependencies. It then returns ALLOW, DENY, MODIFY, STEP-UP, HOLD, or DEFER.

Revalidate

Immediately before the state change, Limren checks the decision again. Stale state, expired authority, changed dependencies, or a changed binding stop the commit.

Commit

COMMIT performs the protected state change. No other stage may write to the protected target.

Verify

After commit, Limren observes the target and compares the result with the intended state. If they differ, Limren records drift and the action moves to reconciliation.

Test the commit boundary.

Run action scenarios, change the conditions between decision and commit, and observe whether Limren commits, holds, verifies, or reports drift.

What you can test

Why the Playground comes first

The Playground is the most concrete way to understand Limren through cause and effect: change the conditions around an action and watch the final boundary respond.

The commit boundary.

The final point at which Limren decides whether a proposal may become an external state change.

Why it exists

A decision can be valid when it is made and invalid seconds later. State can change, authority can expire, a dependency can move, another actor can write first, or the payload can change.

How it works

1. Bind the proposal to its target, payload, authority, evidence, and dependencies.
2. Evaluate the proposal and produce a decision.
3. Wait if approval or another condition is required.
4. Revalidate immediately before the protected write.
5. Commit only if the required guarantees still hold.
6. Observe the real result and verify it against the intended effect.

What crosses the boundary

The boundary does not govern reasoning. It governs a specific state change bound to a target, payload, authority, and the facts that justified the decision.

Typical reasons the boundary stops

• Authority expired.
• A dependency became stale.
• The target version changed.
• The payload no longer matches the approved proposal.
• The action is a duplicate.
• A required approval is missing or no longer valid.

Action envelope.

An action carries the values that must remain bound from decision through commit: actor, target, payload, authority, evidence, dependencies, and constraints.

Current Playground shape

The current public Playground represents an action with fields such as actor, action, target, evidence, and approval.

{
  "actor": "workflow-agent",
  "action": "set_status",
  "target": {
    "resource": "resource-42"
  },
  "payload": {
    "status": "ready"
  },
  "authority": {
    "approval": "APR-2291"
  },
  "dependencies": [
    {
      "resource": "dependency-A",
      "expected_version": 81
    }
  ]
}

What Limren needs to reason about

Why bindings matter

The action that executes must be the action Limren evaluated. If the payload, target, authority, or evidence changes, the old decision must not carry over.

Decision lifecycle.

A verdict tells the system what may happen next. It does not itself perform the protected write.

Verdicts

Approval is not execution

Human approval can satisfy a decision requirement, but it does not bypass commit-time checks. The target, payload, authority window, dependencies, and duplicate state still have to be valid when the write is attempted.

Compound effects

Several actions can each be safe on their own and unsafe together. Limren can delay them, serialize them, require joint approval, or hold the change set until the combined constraint is satisfied.

Reality answers back.

Commit records what Limren sent. Verification checks what the external system actually became.

Intended state vs observed state

Verified

If the observed state satisfies the intended effect, the execution can be recorded as verified.

Drift

If reality differs from the intended effect, the mismatch becomes explicit drift. Limren should not silently treat “request accepted” as equivalent to “desired business state achieved.”

Reconciliation

If verification finds drift, Limren must decide what happens next. That can mean a safe retry, a compensating action, human review, or holding dependent work.

Integration patterns.

Protected mutations must pass through the commit boundary. Agents and applications can read and propose, but they must not bypass Limren to change protected targets.

Target architecture

Protected write rule

Do not give agents independent credentials for protected mutations. The commit worker should be the only component that can send the protected state change.

Read and propose

Reading state and proposing a change do not require write access. The real mutation stays behind one enforceable commit path.

Idempotency & duplicate execution.

A retry should not become a second business effect.

Why duplicates happen

Networks retry. Workers restart. Clients time out. Agents replay. Limren must tell a retry of the same action from a genuinely new action.

Commit-time check

The commit path should check whether the same logical mutation has already been applied or is already in flight before it touches the real target.

Keep the duplicate decision linked

The evidence record should make it possible to show that the duplicate was recognized and that no additional protected write was attempted.

Preconditions & conflict.

The strongest commit is one the target itself can reject if the expected state is no longer true.

Strict

The target enforces a version, ETag, compare-and-set value, transaction condition, or equivalent precondition as part of the write.

Fenced

Exclusive writer control is established through a lease, lock, fencing token, or similar mechanism. This can reduce competing writes when a native target precondition is unavailable.

Non-strict

The system can check immediately before sending, but the target cannot guarantee that nothing changes between the check and the actual write.

STALE vs CONFLICT

STALE means Limren detects drift before the write is sent. CONFLICT means the target rejects the attempted write because its enforced precondition no longer holds.

Failures, drift & recovery.

Stopping an unsafe state change is only one failure case. Limren also records what failed, whether anything changed, and what must happen next.

Before send

Examples include expired authority, stale dependencies, invalid payload binding, duplicate execution, or an unmet target precondition. No protected write should be attempted.

Target rejection

A target can reject a conditional write because its version or precondition changed. Limren records this as CONFLICT.

After commit

The external system can accept a request and still end in the wrong state. Verification records that mismatch as drift.

Recovery actions

Recovery can include retrying a safe idempotent operation, producing a compensating change, escalating to an approver, serializing related work, or holding dependent actions until reconciliation completes.

Action model.

This example shows the information Limren needs to bind to a proposed state change.

Current documented shape

{
  "actor": "checkout-agent",
  "action": "restart_service",
  "target": {
    "resource": "checkout-api",
    "environment": "production"
  },
  "evidence": {
    "id": "E-81",
    "observed_version": "81"
  },
  "approval": "OPS-2291"
}

Fields

Decision record.

A decision record states the outcome, why it happened, the versions Limren compared, and whether commit was attempted.

Documented example

{
  "decision": "HOLD",
  "reason": "DEPENDENCY_STALE",
  "dependency": "dependency-A",
  "expected_version": 81,
  "actual_version": 84,
  "commit_attempted": false
}

Interpretation

The decision was made when dependency-A was version 81. At commit time it was version 84. Limren returned HOLD and did not send the state change.

Evidence model.

Evidence records what the action depended on, what Limren decided, whether commit was attempted, and what the target returned.

Minimum useful evidence

• Principal or actor identity.
• Authority or approval reference.
• Target identity.
• Evidence identifier and observed version/freshness signal.
• Decision outcome and reason.
• Whether a real commit was attempted.
• The observed post-commit state when execution occurs.

Why the record should be durable

A later reviewer should be able to reconstruct the decision from the original evidence. Newer state must not overwrite the evidence that was used at the time.

State transitions.

Limren tracks proposal, decision, commit, and verification as separate states. An action is not treated as successful just because a request was accepted.

Happy path

Blocked paths

Withdrawn intent

A proposal can be withdrawn or replaced before commit. A withdrawn intent should not later reappear as an executable mutation.

Error model.

Control outcomes such as HOLD are not transport failures. Reason codes explain why an action did not proceed.

Currently demonstrated reason

Control outcome vs technical failure

DENY, HOLD, or STEP-UP are valid control outcomes, not necessarily infrastructure errors. A network timeout, target rejection, worker failure, or verification mismatch belongs to a different layer of the model.

Glossary.

The shortest definitions of the terms used throughout the Limren control model.