Worldlines

The file tools (write, edit, …) change a project's main worldline directly, and every agent sees every change. A worldline is the alternative when that is not what you want: an isolated version history of the project for one agent or one task.

Use worldlines when several agents work on one project at once, when an agent should be able to throw its work away, or when you need to know for certain whether a change was applied after a connection dropped.

What a worldline keeps

• An opaque version for every state. Every read reports the version it read.
• Every accepted change as a new version, tagged with its operation id and an optional intent describing why.
• A durable receipt for each accepted operation.
• Scope locks: agents lock the syntax scopes they change before editing. A lock held by another agent fails with scope_locked and names the holder.
• Reverse and redo over accepted history entries. History is never erased.

Worldline data lives beside the project, not inside its file tree, and counts toward the project's and workspace's storage quotas. The main files are not changed by worldline edits.

Every mutation names its operation

Changing actions (apply, fork, reverse, redo) need an operation_id you choose, such as task-17-edit-3. Sending the same id with the same input again returns the original receipt instead of applying the change twice; the same id with different input is refused with identity_conflict.

apply, reverse and redo also need observed: the version the change was made against. A write may observe an earlier version of the same worldline; its result joins the current state. If the observed version is not a state of that worldline, the call fails with stale_frontier.

If a response is lost, don't resend blindly: ask for the receipt with the same operation_id. Either the change was accepted, and you get its result, or it wasn't, and you can send it again. Fughetta never retries a mutation on its own.

Locks

Before editing, call language with action: "scopes" to get scope ids, then lock the scopes you will change. Use :: for file-level changes (write, create, remove, move, mode) or when no syntax scope contains the edit.

• lock takes scopes and an optional environment and returns the current locks.
• unlock releases your named scopes, or one lock by lock_id. Owners may pass force: true to release another holder's lock.
• locks lists current holders, scopes, symbols, environments and places.

A typical session

Fork a worldline from another worldline's version:

{
    "name": "worldline",
    "arguments": {
        "workspace": "acme",
        "project": "app",
        "action": "fork",
        "worldline": "agent-a",
        "name": "agent-a",
        "from": "main",
        "version": "<main version>",
        "operation_id": "task-1-fork"
    }
}

Lock ::, then apply a batch against the version you observed:

{
    "name": "worldline",
    "arguments": {
        "workspace": "acme",
        "project": "app",
        "action": "apply",
        "worldline": "agent-a",
        "operation_id": "task-1-edit",
        "intent": "Update the greeting",
        "observed": "<version>",
        "changes": [{ "kind": "write", "path": "hello.txt", "text": "Hello from agent A\n" }]
    }
}

A batch is all or nothing: every change is checked before any is published.

Changes

Each item in changes has a kind and a path:

Kind	Fields
edit	offset, count and text, in Unicode scalar offsets of the observed version
write	text or data_base64; optional executable
create	text or data_base64; optional executable
remove	just the path
move	destination: the new path
mode	executable: the new flag

Actions

Action	Arguments	Does
list	optional limit	The project's worldlines: name, version, base version and creator.
inspect	worldline, optional version	The complete file manifest and conflicts of one version.
read	worldline, path, optional version	One file's exact bytes in data_base64.
fork	name, optional from and version, operation_id, intent	A new worldline from that version.
lock, unlock, locks	scopes, environment, lock_id, force	Manage scope locks.
apply	observed, operation_id, intent, changes	One atomic batch.
receipt	operation_id	The recorded apply or fork result.
history	optional limit, cursor	Accepted operations, newest first.
reverse, redo	observed, operation_id, target	Undo or restore one history entry.

list and history return at most the workspace's list_max_entries items and set truncated when there are more.

In the console

A project's History tab lists its worldlines and, for the selected one, its history records: action, operation id, caller, time and intent. Choosing a record shows the version information of its resulting state. The tab only reads and does not show file contents.

The Insights tab shows what each software client changed and where those changes appear. It reads bounded records and current placements; it does not write a contribution record.

Access

Anyone who can use the project can use its worldlines. Locks protect concurrent edits inside one worldline, not access to a worldline or project.