Keep agent decisions coherent with a changing world.

A validation core connecting changing sources to a guarded action gate

How it works · Install · Evidence · Develop · Evidence index

PREMiSE lets an agent know whether the facts behind its next action are still current — and makes it re-check them when they are not.

The source system remains the source of truth. GitHub, a file, a database row, or an API still owns its data; PREMiSE supplies the coherence boundary between that mutable world and the agent's final action.

PREMiSE 2 is the current candidate protocol. The public HTTP contract is premise/2, and the current SDK candidate is @premise/sdk@2.0.0-rc.2. premise/1 and premise/1.1 are frozen compatibility specifications. PREMiSE NEXT contains experimental semantics and is not a stable protocol surface. This repository is a serious candidate release, not a universal production or GA claim for every connector and deployment.

The smallest useful PREMiSE integration is a guarded change, not a new memory database. An adapter observes a source and its version; the agent can reason for as long as it needs; the final write is accepted only through the source's own conditional boundary.

const session = premise.session({ tenant: "acme", adapter });
const prepared = await session.prepareAction({
 source: "github://acme/service/pull/42",
 action: { type: "merge" }
});
const outcome = await prepared.commitIfFresh();
if (outcome.status === "blocked") {
 console.log(outcome.code); // e.g. STALE_SOURCE
 // Observe again and make a new decision. Do not replay the old premise.
}

guardedWrite() is the one-shot form. Both paths fail closed when the adapter cannot provide an atomic conditional action. See the product golden path and open the dependency-free Agent Change Control demo to see the stale-write boundary in plain language.

PREMiSE is host-agnostic. You do not need to install this monorepo, a database, or a cloud service to give an agent the protocol workflow and its standalone MCP tools.

npx --yes --package github:Dafenxz0/premise-protocol#v2.0.0-rc.2 premise-install --agent all --project .

For an offline or reviewed checkout, the equivalent explicit path is:

git clone --depth 1 --branch v2.0.0-rc.2 https://github.com/Dafenxz0/premise-protocol.git .premise-source
node .premise-source/plugins/premise-codex/install.mjs --agent all --project .
node .premise-source/plugins/premise-codex/install.mjs --check --agent all --project .

The default is zero-config SELFTEST: it verifies that the copied server starts and responds, but it is not a local memory store or a truth oracle. For remote mode, set PREMISE_MODE, PREMISE_BASE_URL, PREMISE_TENANT and PREMISE_TOKEN in the agent process environment. Never put credentials in .mcp.json. See the agent installation guide for Windows PowerShell, remote mode and uninstall details.

An agent can read config@v41, spend several seconds reasoning, and then attempt a write after another process has already published config@v42. Ordinary memory can preserve the old observation perfectly and still make the action unsafe.

PREMiSE attaches the observation and its version to the decision. Immediately before the side effect, the protocol checks that the premise is still usable. If the world moved, the agent revalidates or stops instead of silently acting on an obsolete plan.

flowchart LR
 S["Mutable source<br/>GitHub · file · DB · API"] --> O["Observe<br/>evidence + version"]
 O --> D["Derive<br/>decision + dependencies"]
 D --> C{"Check before action"}
 C -->|"FRESH"| U["USE<br/>conditional action"]
 C -->|"STALE"| R["REVALIDATE<br/>refresh and decide again"]
 C -->|"INVALID / UNKNOWN"| X["REJECT / STOP"]
 R --> C

The protocol keeps the important state small and explicit:

PREMiSE validation core connected to files, agents, databases and a guarded action gate

_{One boundary, many sources: the connector owns the data and the conditional write; PREMiSE owns the decision's validity.}

The table below is a snapshot of the deterministic local coherence-storm runner with the default seed premise-next-storm-20260814. Reproduce it with node benchmarks/premise-next/storm/runner.mjs. These numbers are useful for checking invariants in this repository; they are not a distributed capacity result, a provider-cost study or a promise that every connector behaves identically.

The following campaign used two isolated Codex/Luna Max agents on the same SkillProof task, then a blind evaluator, plus six separate mutation worlds with 300 deterministic tasks. It is deliberately shown as a safety/cost trade-off: the result supports a strong freshness and action-safety signal, but it does not yet support a claim that PREMiSE uses fewer raw requests.

What this says: PREMiSE prevented every unsafe action in this campaign and correctly handled every changed or errored source. The baseline used 29.45% fewer raw calls because it skipped validation and guards, but it acted on stale state. This is a promising safety result, not yet an efficiency victory. The full methodology and claim boundary are in the mutable-agent campaign record.

For the assumptions, seeds, limitations and negative results, start with the evidence index and PREMiSE NEXT status. The current evidence does not justify claims that PREMiSE is universally safer, cheaper, production-ready for every connector, or independently validated by an external holdout.

Requirements: Node.js 24 and pnpm 10.

The public integration surface is @premise/sdk, an ESM-only Node 24 client for the premise/2 HTTP API. It has no runtime dependency on this monorepo and is tested in three external projects without workspaces:

npm install @premise/sdk@2.0.0-rc.2

The registry publication is still a separate release step for this candidate. The repository gate already builds the package, creates a tarball, installs it with npm in clean GitHub-like, REST and filesystem consumers, and records the registry status as NOT_RUN until a release is intentionally published. See the adoption and reality wave for the exact claim boundary.

For agents working with mutable sources, the repository also ships a PREMiSE Skill and a source Codex plugin. They teach the workflow; the runtime and connector still enforce authorization and conditional writes. The plugin includes a dependency-free MCP launcher that defaults to SELFTEST mode and can use REMOTE mode with PREMISE_BASE_URL; its copied-install gate is documented in the isolated Codex/Luna experiment.

corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm test

Run the smallest end-to-end example:

pnpm example:quickstart

The source is examples/quickstart.mjs. It uses the current PremiseSession contract, verifies a USABLE decision, and finishes through a conditional adapter callback. The connector remains responsible for authorization and its atomic write (CAS, ETag, transaction or equivalent).

const session = premise.session({ tenant: "acme", adapter });
const source = await session.observe("github://acme/config");
const plan = await session.derive({
 claim: "The config is ready to publish",
 from: [source],
});
const check = session.check(plan);
if (check.decision === "USABLE") {
 await session.act({ premise: plan, action: { type: "publish-config" } });
}

This sketch shows the boundary, not a universal connector API. See the API guide, session API and HTTP adapter example for the exact contracts.

PREMiSE does not decide whether a source is morally, legally or semantically true. It does not replace source-of-truth systems, solve retrieval, or make an agent's plan correct by itself. It provides a deterministic coherence boundary: a decision may proceed only when its recorded premises still satisfy the policy required by the action.

The next evidence gate is connector-backed and independent: credentialed PostgreSQL and multi-process crash recovery, durable random-access journal storage, the remaining cross-language guarded-action vectors, external holdouts and provider-cost campaigns. Anything requiring credentials or external infrastructure must remain explicitly skipped until its infrastructure and manifests are present.

Run the relevant package tests and the full validation suite before opening a pull request. New benchmark claims should include the frozen workload and seed manifest, adapter/runtime version, evaluator rules, raw trace digest, denominators and negative or inconclusive results.

pnpm build
pnpm test
pnpm conformance:next

Generated campaign artifacts belong outside the source tree unless a document explicitly treats them as a fixture. If a connector, store or deployment guarantee is not represented by a passing conformance test and published evidence, treat it as work to validate — not as an existing promise.