Unify declared Resource bindings and linked records around one typed Resource reference

[schickling-assistant]

Problem

st2 now has two durable ways for an agent to point at a Resource:

• Agent Spec bindings carry an agent-local name plus an open _tag and exact Resource URI; and
• st2 resource add|ls|read|remove stores agent-owned link records with a URL, relation, title, tags, and body.

These represent different relationship lifecycles around the same underlying concept, but they use different descriptor schemas and read surfaces. #62 clarifies the current distinction and explicitly leaves unification as a separate question.

Open question

Could both surfaces share one typed Resource reference while retaining distinct tagged edge semantics?

ResourceRef = { _tag, uri }

AgentResourceEdge =
  | Binding { name, resource: ResourceRef }
  | Link { id, relation, resource: ResourceRef, title?, tags, body? }

A binding remains publisher/CAS-controlled Agent Spec state. A link remains agent-owned append/remove state for outputs, references, and other observed relationships. Both edges use the same Resource type and URI identity.

Constraints

• Do not turn linked outputs into repeated Agent Spec rewrites.
• Preserve the different mutation authorities and lifecycles of bindings and links.
• Do not introduce a Resource registry or generic external-resource mutation authority.
• Keep unknown Resource types and URI schemes open.
• Resource-edge changes must remain non-disruptive to healthy running tasks.
• Define an explicit migration for existing url link records if the wire format changes.

Questions to resolve

• Should st2 resource ls return both edge variants, or expose separate declared and linked projections?
• Should resource add require both _tag and uri, or derive a default tag from the URI scheme?
• Does relation remain open text or become a small tagged core with extensions?
• How should consumers deduplicate several edges that reference the same Resource URI?

Non-goals

• Generic Resource resolution.
• Mutating the external object named by a Resource URI.
• Making possession of a URI grant authority.

[schickling]

Filed #256 as the stronger form of the _tag sub-question raised here ("Should resource add require both _tag and uri, or derive a default tag from the URI scheme?") — namely whether the field should exist at all.

It carries fleet measurements: across 1031 live bindings, _tag equals the URI scheme in 96.9%, and every one of the 32 exceptions involves a generic scheme — 31 of them defects rather than legitimate uses.

Note the direct tension with this issue's constraint "Keep unknown Resource types and URI schemes open": 53 of those bindings use types with no owning profile, which is what an open namespace permits. Worth settling #256 first, since dropping the tag would collapse ResourceRef = { _tag, uri } here to the URI alone.

[schickling]

Downstream work on schickling/dotfiles#1824 produced a useful refinement for this issue.

For the immediate workflow, we plan to keep the two current meanings explicit:

• st2 agent resource ... (the direction explored in Explore mediated Agent Spec Resource binding mutations #231) would mediate canonical Agent Spec Resource-binding mutations.
• The existing top-level st2 resource ... continues to manage linked output/reference records.

That is intentionally a narrow near-term choice, not a claim that the overlapping concepts and CLI surfaces are ideal. This issue remains the right place to rethink and possibly unify them.

Questions the follow-up should settle:

1. Are an Agent Spec binding and a linked record two projections of one typed Resource reference, or genuinely different concepts?
2. If they remain distinct, should their CLI names make that distinction obvious (for example, agent resource versus link/reference)?
3. What is the clean migration path for existing st2 resource users?
4. Since Consider dropping the Resource binding _tag: the URI scheme already carries the type in 96.9% of live bindings #256 removed the _tag field from Resource references, what discriminator should the proposed shared type use now: URI scheme, relation, or an explicit kind?

This lets #231 solve safe mutation without prematurely cementing the long-term Resource ontology or CLI shape.

[schickling-assistant]

Refuted on measurement

Design interview 2026-08-27 resolved this against a live catalog of 655 agent declarations. The proposal here — one shared ResourceRef behind both bindings and link records — does not survive the data.

The two planes never name the same Resource. 889 distinct binding URIs, 233 distinct link-record URLs, zero coinciding — exact match and normalized across all five schemes both planes used (file, worktree, git-commit, https, st2-message). 81 of the 82 link-record-carrying declarations also carried bindings, so they coexisted constantly and still never named one thing.

The disjointness is semantic. Bindings carry what an agent is for: 728 self-state carriers, 378 work inputs. Link records carried what it made: 196 of 241 were output/produces/evidence/verified. Where a declared worktree and a link output shared a path the relation was containment — the product inside the input — not identity.

So a shared descriptor deduplicates nothing and joins nothing.

Also, this issue's proposed shape assumes a field that no longer exists. ResourceRef = { _tag, uri } — _tag was removed and reason made required in d29c37f, "feat(agent-spec): simplify resource references" (#307, 2026-08-23). The live shape is {name, uri, reason, inactive-reason?} with typing by URI scheme. #60 and #261 carry the same stale assumption.

What the real problem turned out to be. The 45 non-product link records name it: supervises, reference, current-work (which duplicates the work binding), depends-on-slice-*, blocked-design — dependency edges filed in a products store. Agents wrote them there because a binding required publisher authority plus whole-declaration CAS republication, while a link record required one file write. The drift was caused by write-cost asymmetry, not by two relations.

The resolution retires the link plane entirely (it was write-only — the only reader in the source tree was its own ls/read verb — adopted by 12.5% of declarations and decaying, superseded by axe work update --artifact/--pty) and gives st2 resource mediated write verbs, which is what #231 asked for.

Decisions and evidence: docs/vrs/.decisions/0008-the-linked-record-plane-is-retired.md, docs/vrs/07-resource/spec.md, docs/vrs/07-resource/.experiments/2026-08-27-resource-read-surfaces.md. Pending upstream maintainer approval; leaving this issue open for that.

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