Partial changes and conflicts

A mutation binds to Host identity, project identity and a base revision. Read a coherent snapshot and find the intended resource before building a ChangeSet.

Edit a macro name

This fragment assumes an approved, connected client, a selected macroId and a cancellation token:

using System.Text.Json;
using StreamingHub.Api.Client;

var snapshot = await client.GetCompleteSnapshotAsync(ct: token);
var command = new ChangeSetDraft(snapshot)
    .SetMacro(macroId, "Name", JsonSerializer.SerializeToElement("Updated name"))
    .Build();
await client.ValidateAsync(command, token);
var result = await client.ApplyAsync(command, token);

Select a macro by its stable resource ID, not display text. With project.read, call GetResourcesAsync("macro", ct: token) and follow NextPageToken where present. Read the selected resource before editing. Changes require project.write; reading content-bearing configuration can additionally require project.configuration.read.

Validate is a dry run, not a reservation. Another client can commit before Apply. On revision_conflict, retain the draft, refresh and show the differences. Do not silently rewrite its base revision.

Parameters and resources

Use step addresses read from the graph and field IDs from the current schema. A step path is revision-relative, not a permanent ID. Batch compatible semantic operations for atomic publication.

Plugin entity/settings writes use their own resource versions. Detached validation must not mutate live plugin state. An active run keeps the configuration captured for it; an edit affects later accepted work.

Undo is a new compensation command against current state. It can conflict, does not reverse external effects and is not a persistent undo history across Host restarts.

Run and save separately

Applying an edit changes Core's active definitions. It does not implicitly start an automation or save the project file. With the respective approved scopes, these fragments start a selected automation and track Save:

// Requires project.read, runtime.control and runtime.read.
var snapshot = await client.GetCompleteSnapshotAsync(ct: token);
var start = new RuntimeStartCommand(Guid.NewGuid(), snapshot.Identity, automationId);
var acceptedRun = await client.StartRunAsync(start, token);
if (acceptedRun.RunId is { } runId)
{
    var run = await client.WaitForRunAsync(runId, ct: token);
    Console.WriteLine(run.Status);
}

// Requires project.read and project.files. Core must have an open project.
var snapshot = await client.GetCompleteSnapshotAsync(ct: token);
var save = new ProjectFileCommand(Guid.NewGuid(),
    snapshot.Identity.HostInstanceId, snapshot.Identity.ProjectId);
var acceptedSave = await client.SaveAsync(save, token);
var operation = await client.WaitForOperationAsync(acceptedSave.OperationId, ct: token);
Console.WriteLine(operation.Status);

These fragments also need StreamingHub.Api.Contracts. Inspect terminal status and safe errors rather than treating acceptance as completion. waiting_for_interaction needs an authorized responder. Running an automation can perform external effects. Keep each command ID before sending it and use command recovery if the response becomes uncertain.