subjectresolve

type Env struct {
	// Relations reads one object's user-mapping relations from SpiceDB.
	Relations RelationReader
	// SessionAnnotations returns the owning AgentSession's annotations
	// (for session-derived references like trigger-author). Nil when no
	// session context exists.
	SessionAnnotations func(ctx context.Context) (map[string]string, error)
}

type RelationReader interface {
	// UserSubjects returns the bare canonical ids of the `user:` subjects on
	// the given object's relation. Resolution reads "sole_user" only — the
	// durable single-claimant authority — never the session-membership
	// "user" relation, which is legitimately multi-claimant and may be
	// mid-derivation.
	UserSubjects(ctx context.Context, objType, objID, relation string) ([]string, error)
}

type Resolution struct {
	// Subject is the bare canonical user id; empty when unresolved.
	Subject string
	// SubjectProven reports whether the resolver VOUCHES that the platform
	// links Subject to the reference — true only for a resolution backed by a
	// linkage authority (a resource's sole_user relation, trigger-author's
	// recursion into one). The email resolver leaves it false: it
	// canonicalizes any well-formed address into a subject in FORM only, with
	// nothing behind it, so a consumer must apply its own existence bar
	// before treating an unproven subject as a real platform user. The zero
	// value is unproven on purpose — a future resolver that forgets to claim
	// proof gets the stricter treatment, not the looser one.
	SubjectProven bool
	// Reason says why resolution failed, in words an agent may relay.
	Reason string
}

type Resolver interface {
	// Usage returns the reference form and a one-line description, exactly as
	// shown to the model in tool schemas (see Usages). Form is the literal
	// syntax (e.g. "email:<address>"); description says whom it resolves
	// (e.g. "the platform user with this verified email").
	Usage() (form, description string)

	// TryResolve attempts to resolve ref under this resolver's scheme.
	// matched=false means ref is outside this resolver's scheme entirely, and
	// Resolve tries the next registered resolver. matched=true commits to this
	// resolver's outcome (res, err) even when res is unresolved.
	TryResolve(ctx context.Context, ref string, env Env) (res Resolution, matched bool, err error)
}

type Usage struct {
	Form        string
	Description string
}