Files
zeekayandHanzo Dev 8efed70ea2 fix(six): one word, one body, one shape across the three SDKs
Thirteen places where this SDK and the other two answered the same question
differently. Every one is now what the served handler reads, or what HIP-0044
says where the handler is silent.

Measured against the server, not inferred:

- search speaks kinds, not doctype addresses. `/v1/search` matches `doctypes`
  against kb.page, kb.memory and kb.source EXACTLY and silently drops anything
  else (knowledge/subsystem.go, sanitizeDocTypes), so Opts{Kinds: ["page"]} —
  the word the contract uses — was narrowing the query to nothing at all. The
  kind maps to the address on the way out and back on the way in, and a doctype
  from another corpus passes through untouched. kb.Doctype and kb.Kind are the
  one place either spelling appears.
- kb.Put lets the store decide whether a document exists. kb.page is autonamed
  `field:slug`, so a page IS its name and carries one whether it exists or not:
  reading a present name as "it exists" left no way to create a page — the PUT
  404s forever and a POST with no slug is refused for the missing field. The PUT
  goes first and a 404 is followed by the POST.
- A write body is field data and nothing else. The framework validates against
  DocType.Fields and drops what it does not declare, and `name` is not a field
  of any of the three: a page is named from `slug`, a memory and a source are
  hash-named. `url` belongs to a source. An empty field is left out so the
  doctype names the required one that is missing.
- kb.Filter takes Order, and Links takes a project. `/v1/framework/{doctype}`
  serves order_by and `/v1/knowledge/graph` serves ?project=; only one SDK had
  either.
- Import takes (format, data, project). Two values and an option are not an
  aggregate, so kb.Export is gone.
- policy_denied and entitlement_required do not exist. Neither string appears
  anywhere in hanzoai/cloud, so a 403 read as denied on one of them would hand
  an unauthenticated caller a cure for a refusal nobody made. The 403 refusal
  set is insufficient_balance and spend_cap_exceeded, the two cloud emits.
- A 402 with no readable body carries no code. payment_required is a real code
  — it is the `error` member of every cloud.Refusal — so writing it where the
  body said nothing made the spend gate's refusal and an unparseable body the
  same value.

And where the shape had drifted from what a reader needs:

- Money counts minor units, not cents: hundredths for USD, whole yen for JPY,
  thousandths for KWD, and "cents" is false for two of those three.
- Balance.Reserved, not Held. The wire says `holds`; `held` is an arm of an
  answer, and one word for two facts is what the naming rule prevents.
- Vocabulary.Rules, because it is a list. The wire member stays `rule`.
- audit.List reports the server's own count. A per-page count under a Request
  filter is not "what the filter matched across every page", and All now counts
  what the server sent against that total rather than what survived a narrowing
  the server never made — so a request filter stops scanning the whole trail.
- A client with no credential fails at the first call, not silently. It used to
  present nothing and let the gateway answer 403, which reads as "your org may
  not do that" rather than "this process never said who it is".

HIP-0044 is amended where the code was right and the document was not: the
authz body spelling, Allowance.spent as a boolean, the wire's `holds`, put's
method choice, Fact's three read-only members, and the name of the fourth
outcome.

go build, go vet, go test ./... and gofmt -l . all clean.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-10 16:24:40 -07:00

144 lines
5.0 KiB
Go

// six — budget, policy, audit, search, kb and graph in one run.
//
// The six are one client because they share one answer type, one refusal
// vocabulary, one instant and one correlation id. This walks that: what the
// wallet holds decides whether to ask, the wallet's own account names the org a
// policy question is scoped to, a search comes back with its degradation stated
// rather than hidden, a graph write answers an id, and that id is what finds
// the row the server wrote about it.
//
// Nothing here is a refusal you catch. A budget that says no and a policy that
// says no are values: the answer's denied arm carries the code and the cures.
//
// HANZO_CLIENT_ID=... HANZO_CLIENT_SECRET=... go run ./examples/six
package main
import (
"context"
"errors"
"fmt"
"log"
"os"
"strings"
"time"
hanzoai "github.com/hanzoai/go-sdk/v8"
"github.com/hanzoai/go-sdk/v8/audit"
"github.com/hanzoai/go-sdk/v8/graph"
"github.com/hanzoai/go-sdk/v8/kb"
"github.com/hanzoai/go-sdk/v8/search"
)
func main() {
ctx := context.Background()
client := hanzoai.New(hanzoai.Options{})
started := time.Now().UTC()
// BUDGET — a count and a sum, which never stand in for each other.
left, err := client.Budget.Left(ctx)
if err != nil {
log.Fatalf("allowance: %v", err)
}
if left.Left == nil {
fmt.Printf("budget %s, calls unbounded\n", left.Plan)
} else {
fmt.Printf("budget %s, %d of %d calls left this %s\n",
left.Plan, *left.Left, left.Limit, left.Window)
}
balance, err := client.Budget.Balance(ctx)
if err != nil {
log.Fatalf("balance: %v", err)
}
fmt.Printf("wallet %d %s available in %s\n",
balance.Available.Minor, balance.Available.Currency, balance.Account)
// POLICY — may this subject write here? The object is org-scoped and the
// org is not something a client may assert, so it is read off the wallet
// the answer above already named.
subject := balance.Account
org, _, _ := strings.Cut(subject, "/")
decision, err := client.Policy.Check(ctx, subject, "write", org+"/graph")
if err != nil {
log.Fatalf("policy: %v", err)
}
fmt.Printf("policy %s write %s: allow=%v %s\n",
decision.Sub, decision.Obj, decision.Allow, decision.Reason)
// SEARCH — one ranked set over the whole corpus, kb included. Partial is
// the field that says a leg was down; an answer that ignores it reads a
// truncated corpus as a complete one.
answer := client.Search.Find(ctx, "runbook", search.Opts{Kinds: []string{kb.Page}, Limit: 5})
hits, err := answer.Value()
var denied *hanzoai.Denied
switch {
case errors.As(err, &denied):
fmt.Printf("search denied (%s): %s\n", denied.Code, denied.Reason)
for _, cure := range denied.Cures {
fmt.Printf(" %s at %s\n", cure.Kind, cure.URL)
}
case err != nil:
log.Fatalf("search: %v", err)
default:
fmt.Printf("search %d hit(s) in %s mode, partial=%v, took %s\n",
len(hits.Items), hits.Mode, hits.Partial, hits.Took)
for _, hit := range hits.Items {
fmt.Printf(" %-10s %s\n", hit.Kind, hit.Title)
}
for _, backend := range hits.Backends {
if backend.Status != "ok" {
fmt.Printf(" %s is %s: %s\n", backend.Name, backend.Status, backend.Error)
}
}
}
// GRAPH — one assertion with provenance and time. Nothing overwrites
// anything, so running this twice records once and counts the second as a
// duplicate.
entity := fmt.Sprintf("example/six/%d", os.Getpid())
wrote := client.Graph.Assert(ctx, []graph.Fact{{
Entity: entity,
Relation: "title",
Value: "the six capabilities, exercised",
At: started,
Source: "go-sdk/examples/six",
}})
written, err := wrote.Value()
var held *hanzoai.Held
switch {
case errors.As(err, &denied):
fmt.Printf("graph denied (%s): %s\n", denied.Code, denied.Reason)
case errors.As(err, &held):
fmt.Printf("graph held %s on %s: %s\n", held.ID, held.Clause, held.Reason)
case err != nil:
log.Fatalf("graph: %v", err)
default:
fmt.Printf("graph %d recorded, %d duplicate, %d refused %v\n",
written.Recorded, written.Duplicate, written.Refused, written.Reasons)
resolved, err := client.Graph.Resolve(ctx, entity, "title", time.Time{})
if err != nil {
log.Fatalf("resolve: %v", err)
}
if resolved.Known {
fmt.Printf("graph in force: %q from %s\n", resolved.Winner.Value, resolved.Winner.Source)
}
}
// AUDIT — the trail of what just happened. Every answer carries the
// x-request-id, and that is the join: the server wrote the row, the client
// only reads it.
//
// The route accepts no requestId filter yet, so Filter.Request narrows
// client-side over the window this run opened. It stops being a scan the
// day GET /v1/audit takes the id every row already carries.
fmt.Printf("audit rows for request %s\n", wrote.Request)
for event, err := range client.Audit.All(ctx, audit.Filter{Request: wrote.Request, Since: started}) {
if err != nil {
log.Fatalf("audit: %v", err)
}
fmt.Printf(" %s %-24s %-8s %s %s\n",
event.At.Format(time.RFC3339), event.Action, event.Result, event.Method, event.Path)
}
}