Define optional observational resolution evidence for Resource bindings

[schickling-assistant]

Current boundary

Current main already parses and preserves named typed Resource descriptors, exposes them through st2 agents --json, and keeps Resource-only declaration changes out of task launch identity and healthy-task replacement. Canonical evals consume the same native Agent Spec vector.

The remaining question is deliberately narrower: if an owner provides an optional resolver, what trustworthy observational evidence may st2 expose to read-oriented consumers?

Required invariants

• Resolution is optional observation, not Agent Spec admission.
• An unresolved, unsupported, missing, unauthorized, or unreachable resource must not become a generic launch, readiness, materialization, restart, replacement, or teardown gate.
• Resource-only observation changes must not degrade or disrupt an already-running agent task.
• URI possession confers no authority, access, or grant.
• st2 remains complete from the ordinary catalog folder without CAS, a resident database, a reachable resolver, or another online service.
• Existing native gates, including workspace and materialization validation, retain their own contracts.

A resolver may report candidate states such as available, missing, unauthorized, unreachable, or unsupported, but the generic envelope must not pretend that one universal taxonomy captures every downstream type. The resolver owner must define what its evidence means and how stale observations are represented.

Existing native seam

The portable declaration and inspection seam is already present:

• Agent Spec carries zero or more uniquely named Resource bindings;
• the binding name is an agent-local semantic role;
• _tag identifies the downstream type contract;
• uri is preserved as exact absolute identity;
• st2 agents --json projects descriptors without resolving them; and
• Resource-only declaration changes adopt healthy work without stop, replacement, or relaunch.

The missing seam is only optional resolution evidence and a trustworthy read-side consumer of it.

Acceptance direction

A future implementation should prove that:

• selected descriptors and their observational state are inspectable without resolving external payloads during launch;
• unsupported or unavailable resolvers remain visible and non-destructive;
• transient resolver failure cannot stop, replace, or suppress declared work;
• observation is attributable to the binding and resolver that produced it; and
• removing the resolver leaves ordinary catalog inspection and runtime behavior complete.

Outside st2's generic contract

Type-specific cardinality, a special work role, “no work means idle,” and A -> no holder -> B handoff semantics belong to the owning resource type or eval corpus. They are not generic st2 Agent Spec law. Publication, resolution, launch, readiness, and teardown remain distinct states.

Open questions

1. Which component owns each optional resolver and its trust boundary?
2. Is observational state exposed through catalog inspection, doctor, or a separate read-only surface?
3. What freshness and provenance accompany a result?
4. Which minimal states, if any, are safe across resource types?
5. How do derived runtime observations remain distinct from the declared Resource identity?

Related

• VRS R20–R21: portable Resource bindings and nondisruptive observation
• Explore typed resource URI bindings in Agent Spec evals#41: portable typed Resource bindings
• Keep early Resource consumers read-oriented #61: read-oriented consumer boundary (satisfied by R20–R21 and this narrowed issue)
• Expose desired versus observed launch generation for adopted tasks #40 / Adoption matches by identity only, so a task running a superseded command is adopted as current and reported healthy #44 / docs(vrs): define no-CAS launch drift boundary #77: desired-versus-observed runtime boundaries

[schickling-assistant]

Partial answer: one resolver owner is now named

Design interview 2026-08-27 settled a narrow piece of open question 1 ("Which component owns each optional resolver and its trust boundary?").

working-state is the first Resource profile st2 itself owns, resolved by st2 context and realized at <agent-dir>/resources/context/now.md (see #261). That collides with R20's "st2 does not register schemes", so rather than leave R20 contradicted, a new requirement names the exception:

R35 st2-owned Resource profiles: st2 may own a small, enumerated set of Resource profiles for state it already writes. An st2-owned profile declares its scheme, its resolver, and its realization, and is exempt from R20's rule that st2 does not register schemes, only for the schemes named here. The initial set is working-state, resolved by st2 context and realized at the agent's working-state document. An st2-owned binding grants no authority, and its absence is not an error, a launch gate, a readiness gate, or a restart trigger.

That last clause is deliberately the invariant list from this issue: resolution stays optional observation, and a missing carrier is not a gate.

Worth noting for anyone working from this issue's text: it describes bindings as carrying _tag. That field was removed and reason made required in #307 (2026-08-23); the live shape is {name, uri, reason, inactive-reason?} with typing by URI scheme. #122 and #261 carry the same stale assumption.

The rest of this issue — the general resolver contract, freshness and provenance, the candidate state union — is untouched and still open. R35 names an owner for one profile; it does not define the generic resolution surface this issue asks for.

Decision: docs/vrs/.decisions/0009-working-state-is-a-declared-carrier.md. Pending upstream maintainer approval.

Posted on behalf of @schickling

field	value
agent_identity	unknown
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	Claude Code
agent_tool_version	2.1.237
agent_runtime	Claude Code 2.1.237
tooling_profile	dotfiles@11eaf2d-dirty