Go SDK

Install

Stable baseline: v1.0.1. The recording and Semiotic Probe release is v1.1.0-dev.1, published on GitHub and verified through the Go module proxy.

go get github.com/haltstate-ai/sdk-go@v1.1.0-dev.1

Install this published release explicitly to use recording and Semiotic Probes. Existing integrations remain on the Standard contract unless enrolled for replay. Semiotic Probes use an isolated model hook, your existing tenant API key and the server-managed low-frequency schedule.

Guard shape

client, err := haltstate.NewClient(haltstate.Config{
  TenantID: os.Getenv("HALTSTATE_TENANT_ID"),
  APIKey: os.Getenv("HALTSTATE_API_KEY"),
})
if err != nil {
  return err
}

const operatorEpoch = "11111111-2222-4333-8444-555555555555"
destinationKey := "refund:lge_123"
guardKey := "hsr1:" + operatorEpoch + ":" + destinationKey
reportID := "40000000-0000-4000-8000-000000000501"
permit, err := client.Guard(
  ctx,
  "refund.create",
  map[string]interface{}{"amount": 126, "currency": "USD"},
  guardKey,
  "retail-refund-agent",
)
if err != nil {
  return err
}
if err := permit.ValidateForExecution(); err != nil {
  return err
}
if actionErr := executeRefundOnce(permit); actionErr != nil {
  message := actionErr.Error()
  report := haltstate.GuardOutcomeReport{
    ReportID: reportID,
    Outcome: "error",
    Error: &message,
  }
  receipt, reportErr := client.ReportGuardOutcome(ctx, permit, report)
  if reportErr != nil {
    persistReconciliation(permit, report)
    return reportErr
  }
  persistReceipt(receipt)
  return actionErr
}
report := haltstate.GuardOutcomeReport{
  ReportID: reportID,
  Outcome: "success",
  Result: map[string]interface{}{"destination_key": destinationKey},
}
receipt, reportErr := client.ReportGuardOutcome(ctx, permit, report)
if reportErr != nil {
  persistReconciliation(permit, report)
  return reportErr
}
persistReceipt(receipt)

Persist the exact permit and report envelope for reconciliation if the receipt is uncertain. Retry only ReportGuardOutcome; never rerun the destination action.

Full operation identity

client, err := haltstate.NewClient(haltstate.Config{
  TenantID: os.Getenv("HALTSTATE_TENANT_ID"),
  APIKey: os.Getenv("HALTSTATE_API_KEY"),
})
if err != nil {
  return err
}

const operatorEpoch = "11111111-2222-4333-8444-555555555555"
destinationKey := "refund:" + ledgerEntryID
guardKey := "hsr1:" + operatorEpoch + ":" + destinationKey
reportID := "40000000-0000-4000-8000-000000000501"
permit, err := client.GuardWithOptions(
  ctx,
  "refund.create",
  map[string]interface{}{"amount": 126, "currency": "USD"},
  guardKey,
  haltstate.GuardOptions{
    AgentID: "retail-refund-agent",
    Resource: "refund/" + ledgerEntryID,
    RiskClass: "low",
  },
)
if err != nil {
  return err
}
if err := permit.ValidateForExecution(); err != nil {
  return err
}
if actionErr := executeRefundOnce(permit); actionErr != nil {
  message := actionErr.Error()
  report := haltstate.GuardOutcomeReport{
    ReportID: reportID,
    Outcome: "error",
    Error: &message,
  }
  receipt, reportErr := client.ReportGuardOutcome(ctx, permit, report)
  if reportErr != nil {
    persistReconciliation(permit, report)
    return reportErr
  }
  persistReceipt(receipt)
  return actionErr
}
report := haltstate.GuardOutcomeReport{
  ReportID: reportID,
  Outcome: "success",
  Result: map[string]interface{}{"destination_key": destinationKey},
}
receipt, reportErr := client.ReportGuardOutcome(ctx, permit, report)
if reportErr != nil {
  persistReconciliation(permit, report)
  return reportErr
}
persistReceipt(receipt)

Replay-enabled SDK contract

The stable retry identity binds the exact agent, action or tool, resource, normalized parameters, risk class, and immutable policy version. With an operator-issued activation epoch, the SDK may create epoch-qualified generated keys only when the caller omitted a key; explicit keys are never changed. Approval expiry blocks a stale permit, while already_started and completed remain terminal. After the side effect, receipt validation requires the durable event ID, receipt hash, received flag, and duplicate marker; retry the same report identity without rerunning the action.

Use this contract only for an explicitly enrolled replay integration. Published release channels and version-specific features are listed above; package installation alone does not activate replay routing.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.