artifactref

Overview ¶

Package artifactref carries Harbor's in-process pass-by-reference tool-argument routing: a tool declares an artifact-reference PARAMETER in its typed input struct, the model supplies an artifact id, and the runtime resolves that id to the stored bytes at DISPATCH so the tool function reads content the model never saw.

Because in-process tool input schemas are reflection-derived from the Go type (internal/tools/drivers/inproc.RegisterFunc -> internal/tools/schema.Derive), a reference parameter is a declared FIELD TYPE rather than a hand-written schema convention:

type SummarizeArgs struct {
    Doc      artifactref.Ref `json:"doc"`
    MaxWords int             `json:"max_words"`
}

func summarize(ctx context.Context, in SummarizeArgs) (Out, error) {
    body, err := in.Doc.Bytes() // the store's bytes, never the model's
    ...
}

The derived schema renders `doc` as a plain string, so the model authors `{"doc": "tool_ab12cd34ef56", "max_words": 200}` and never authors — or reads — content.

The substitution invariant ¶

A resolved artifact value never re-enters the model's context or the observable record. When the runtime substitutes a resolved value into a dispatched tool argument, that value is DISPATCH-LOCAL: it does not appear in the trajectory, in the observation the runtime interleaves into the next chat thread, in any canonical event payload, in an audit payload, or in a log. The model authored an id and continues to see an id; the substitution is the runtime's and it ends at the tool boundary.

The invariant is held three ways, in descending order of durability:

1. A bound on PRODUCTION. Substitute is the ONE call site at which a resolved value enters a dispatched argument, and ScanSubstitutionSites holds it to one mechanically. An invariant about where a value does not travel is enforced most durably by bounding where it is produced; enumerating every place it might arrive is the check that goes stale.

2. A projection bound on the CARRIER. Ref keeps the resolved bytes in an unexported field and projects itself as its id through every serialisation door the runtime has: Ref.MarshalJSON emits the id, Ref.String returns the id, and Ref.LogValue renders the id. A `Ref` that reaches `json.Marshal`, `fmt.Sprintf` or `slog` therefore emits an id rather than content, by construction rather than by discipline.

3. An arrival check at the LLM edge, which lives with the safety net rather than here (internal/llm.findContextLeak).

Extent ¶

This is the IN-PROCESS arm. The consumer runs inside the Runtime, so resolution is a store read and a struct field: no URL, no third party, no egress. Handing a remote consumer something it can dereference is a separate, deliberately unbuilt design — see the routing notes in docs/decisions.md.

Concurrent reuse ¶

Nothing in this package holds mutable package-level state. A Ref is decoded fresh per invocation and lives on the per-call argument value; the resolver rides the dispatch ctx, scoped to the dispatching run's identity, and is never read from a shared artifact.