Undo what narya learned

curl --request POST \
  --url https://api.example.com/v1/refinements/{refinementId}/rollback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "toEventId": "5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/refinements/{refinementId}/rollback"

	payload := strings.NewReader("{\n  \"toEventId\": \"5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({toEventId: '5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b'})
};

fetch('https://api.example.com/v1/refinements/{refinementId}/rollback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/refinements/{refinementId}/rollback"

payload = { "toEventId": "5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "7d1e3a5c-9b2f-4e6a-8c0d-2f4a6c8e0b2d",
  "kind": "memory",
  "scope": "repository",
  "repository": "/Users/dana/repos/midaz",
  "owner": "local",
  "title": "Migrations and the schema document are one change",
  "body": "A new migration file without the matching block in schema.sql fails two tests the moment it lands.",
  "state": "active",
  "origin": "loop",
  "originSessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
  "originEntryId": "8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f",
  "citations": [
    {
      "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
      "entryId": "8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f"
    }
  ],
  "createdAt": "2026-09-07T09:12:00.000Z",
  "activatedAt": "2026-09-07T09:12:00.000Z",
  "hits": 4
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Undo what narya learned

Undoes a refinement and records that it did. THIS IS ALSO THE DELETE: “archive, never destroy” holds here, so the row stops firing, keeps its provenance and its evidence, and stays in the listing — walking backwards from a strange behaviour to the fact that caused it is exactly what the row is for.

With no toEventId the whole history is inverted, back to the creation, and the row lands in rolled-back. Naming an event undoes down to and including that event, which is also how a rollback is itself undone: undo and redo are one verb aimed at different events.

It answers 200 with the row as the rollback left it rather than 204, so narya learned rollback --json has something to print.

POST

refinements

{refinementId}

rollback

Undo what narya learned

curl --request POST \
  --url https://api.example.com/v1/refinements/{refinementId}/rollback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "toEventId": "5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/refinements/{refinementId}/rollback"

	payload := strings.NewReader("{\n  \"toEventId\": \"5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({toEventId: '5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b'})
};

fetch('https://api.example.com/v1/refinements/{refinementId}/rollback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/refinements/{refinementId}/rollback"

payload = { "toEventId": "5c7e9a1b-3d5f-4a7c-9e1b-3d5f7a9c1e3b" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "7d1e3a5c-9b2f-4e6a-8c0d-2f4a6c8e0b2d",
  "kind": "memory",
  "scope": "repository",
  "repository": "/Users/dana/repos/midaz",
  "owner": "local",
  "title": "Migrations and the schema document are one change",
  "body": "A new migration file without the matching block in schema.sql fails two tests the moment it lands.",
  "state": "active",
  "origin": "loop",
  "originSessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
  "originEntryId": "8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f",
  "citations": [
    {
      "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
      "entryId": "8a1d3f5b-7c9e-4a2b-8d6f-0c2e4a6b8d0f"
    }
  ],
  "createdAt": "2026-09-07T09:12:00.000Z",
  "activatedAt": "2026-09-07T09:12:00.000Z",
  "hits": 4
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Authorizations

Authorization

string

header

required

Enforced on every transport, with no exempt operation. A person's request — over the default local unix socket exactly as over a TCP listener — must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011. The socket's file permissions are transport and are not an authorisation.

Path Parameters

refinementId

string<uuid>

required

The refinement's id.

Body

application/json

How far back to undo.

toEventId

string<uuid>

Undo down to and INCLUDING this event. Absent undoes the whole history, back to the creation, which leaves the row in rolled-back rather than deleting it.

Response

The refinement, as the rollback left it.

One thing the harness learned and a person allowed: a distilled memory, or a skill, agent or command definition the model authored. The owner is never something a caller names. script and events are present on getRefinement and absent from the listing. A page carrying every authored program's source is a page nobody can read; the hash is on both, which is what "what was consented to is what runs" is checked against.

string<uuid>

required

kind

enum<string>

required

What a refinement IS. Four values and no more — one vocabulary is what makes "everything this repository taught narya" one question.

Available options:

memory,

skill,

agent,

command

scope

enum<string>

required

How far a refinement reaches. repository is keyed on the canonical checkout path, the same key a trust answer uses; global is the owner's. There is no session here and the absence is a decision: a session-scoped fact lives exactly as long as the conversation that gave it, so it is never a stored row at all.

Available options:

repository,

global

owner

string

required

Whose learning this is.

title

string

required

Maximum string length: 200

body

string

required

The fact's text, or the definition's prompt or description.

state

enum<string>

required

Where a refinement stands. pending is proposed and nothing else — never rendered, never executed, never on a ladder. active is consented and firing. rolled-back is kept for the record. unverifiable is the one that surprises: such a fact is STILL FIRING and says so. Every session it cited has been purged, which is a person deleting a transcript rather than a person retracting a belief.

Available options:

pending,

active,

rolled-back,

unverifiable

origin

enum<string>

required

Which road a refinement came in on: narya's own review of a conversation, a client teaching it through this contract, or an import. Both roads land pending and pass the same consent.

Available options:

loop,

api,

import

createdAt

string<date-time>

required

hits

integer<int32>

required

How many turns this has fired into.

Required range: x >= 0

repository

string

The canonical checkout path, absent at the owner's global scope.

name

string

The ladder identity of the three definition kinds, absent on a memory.

Maximum string length: 128

script

string

The program the model wrote, IN FULL — never a digest and never a path. A person cannot consent to what they were not shown, and what they consented to is what the confined runtime later runs, byte for byte. Present on getRefinement only.

scriptSha256

string

The hash of that program, on the listing as well as the read. It is what the runtime checks the text against before running it.

Pattern: ^[0-9a-f]{64}$

originSessionId

string

The conversation this was learned from. It may name a session that has since been purged, which is what unverifiable reads from.

originEntryId

string

The turn this was learned in.

originActor

string

Who was acting when this came in over the contract.

citations

object[]

The turns this stands on, in the order they were written.

Show child attributes

events

object[]

Everything that has happened to this refinement, newest first. Present on getRefinement only.

Show child attributes

activatedAt

string<date-time>

When a person consented. Absent while pending.

lastUsedAt

string<date-time>

When this last fired into a prompt. It is what eviction is ordered by — a fact that fires often is a fact that earned its place — and it is deliberately never rewound by a rollback.

supersededBy

string<uuid>

The row that replaced this one, if any.

Overview

Host

Sessions

Messages

Events

Lanes

Monitors

Agents

Skills and commands

Permissions

Peers

Packages

Extensions

Workflows

Schedules

Providers

Records

Environments

Sharing

Refinements

Platform

Error handling

Undo what narya learned

Authorizations

Path Parameters

Body

Response