Core Concepts

Safety Model

Safety in NILScript is structural, not a policy bolted on after the fact. Authority is scoped by grant, risk is graded by tier, every write is previewed from system facts, ambiguity is refused, retries are idempotent, and every sentence is recorded.

Grants — scoped authority

A grant is a scoped, budgeted, revocable authorization for a speaker within a workspace. It is default-deny: scopes are an explicit list of allowed verbs, and anything not listed is forbidden.

grant.json

{
  "grant": "grant_acme_agent",
  "workspace": "ws_acme",
  "audience": "third_party_agent",
  "scopes": ["commerce.get_product", "commerce.create_purchase_order"],
  "budget": { "currency": "SAR", "limit": "10000.00", "spent": "1250.00" },
  "expires_at": "2026-06-30T00:00:00Z",
  "revoked": false
}

You can't multiply authority by multiplying heads

A swarm of agents shares one grant and one budget. The budget is enforced before any side effect, so a swarm cannot collectively overspend.

Tiers & the cooling delay

Every proposal carries a tier. A profile sets a floor; a deployment may raise it but never lower it below the floor.

Tier	Behavior
`LOW`	Execute immediately
`MEDIUM`	Execute and notify the owner
`HIGH`	Park pending owner approval
`CRITICAL`	Approve, then wait a 300-second cooling delay before commit

The cooling window is deliberate

The 300-second delay on CRITICAL means even an approved catastrophic action has a window in which it can still be aborted.

Previews from facts

A preview is a system-rendered, human-readable statement of facts — actor, action, counterparty, amount, currency — localized per BCP 47. It is computed from facts the system resolves, never from the values the agent supplied. If a plan cannot be previewed, it cannot run.

Refusals, not errors

When the system declines, it returns a 200 OK refusal with a typed code — not an HTTP error. An AMBIGUOUS hint returns up to eight candidates; an UNRESOLVED hint matched nothing; POLICY_DENIED means no grant authorizes it. Each is a normal outcome the agent or a human can act on.

Idempotency

Every COMMIT carries an idempotency key. A retried commit with the same key replays the original outcome rather than acting twice — and “replayed” is a first-class outcome the system returns, marked as such.

Reversibility tiers

Independent of the consequence tier, every verb declares how far it can be undone:

Tier	Meaning	Example
`REVERSIBLE`	A clean inverse exists	`create` ↔ `delete`
`COMPENSABLE`	An offsetting forward action	`record_payment` → `process_refund`
`IRREVERSIBLE`	No reversal — refused honestly	the default for unmarked verbs

IRREVERSIBLE is a strength, not a gap

The system refuses to pretend it can undo what it cannot. A ROLLBACK against an irreversible verb returns code IRREVERSIBLE, never a silent or phantom write.

Append-only audit

Every sentence is bound, in an append-only log, to the grant it ran under, the policy version in force, the actor, the preview shown, and the outcome produced. Given any outcome, you can reconstruct exactly which grant authorized it, which policy evaluated it, and what the actor was shown before they committed.