[AIT-1138] Deprecate RTPO8d: PathObject#instance wraps primitives (RTPO8f)

[sacOO7]

• Fixes https://ably.atlassian.net/browse/AIT-1138

What

PathObject#instance previously returned undefined/null when the path resolved to a primitive value (RTPO8d). This PR deprecates that clause and replaces it with RTPO8f: a primitive resolution now returns a new Instance wrapping the primitive value. The corresponding UTS test spec is updated to match.

Why

The primitive-null behaviour was the odd one out in the Instance model:

• RTINS1 already defines Instance as "a direct-reference view of a LiveObject or primitive value".
• Primitives already surface as Instances through Instance#get (RTINS5c), so a map entry read via an Instance produced a primitive Instance, while the same entry read via PathObject#instance produced nothing.
• RTINS3b (primitives have no object id) and RTINS4c (Instance#value returns the primitive directly) already specify how a primitive-wrapping Instance behaves — RTPO8d was just blocking the one entry point.

Making instance() total over resolved values gives callers a single, uniform way to capture a point-in-time reference to whatever sits at a path.

Changes

specifications/objects-features.md

• RTPO8d — marked as replaced by RTPO8f, following the existing deprecation convention.
• RTPO8f (new) — a primitive resolution returns a new Instance (RTINS1) wrapping the primitive value.
• RTPO8c (LiveObject → Instance) and RTPO8e (resolution failure → undefined/null) are unchanged.

uts/objects/unit/path_object.md

• objects/unit/RTPO8c/instance-primitive-null-0 becomes objects/unit/RTPO8f/instance-primitive-wrapped-0: asserts the returned Instance exists, has no object id (RTINS3b), and exposes the primitive via value() (RTINS4c).

SDK adoption

Both SDK implementations and their derived UTS tests have been updated to this behaviour and are pending on their respective branches:

• ably-js: _resolveInstance wraps any resolved value; batch() retains its explicit LiveObject check so the 92007 non-LiveObject error is unaffected.
• ably-java: DefaultPathObject.instance() returns the typed Instance for any resolved value; primitive instances remain anonymous (no id member) per the typed-SDK contract.

Follow-up (separate PR)

The typed-SDK spec section (RTTS6e / RTTS3b, #491) still states that instance() on primitive PathObject sub-classes returns null or throws 92007 — that premise is removed by this change and will be reconciled in an individual PR against that branch.

[paddybyers]

Does this need a uts test update?

[sacOO7]

Does this need a uts test update?

Yes, we need to update current test instance() returns null for primitive as per updated spec point.

[Copilot]

Pull request overview

Deprecates the PathObject#instance primitive-resolution behavior that previously returned undefined/null (RTPO8d), replacing it with a new clause (RTPO8f) that returns an Instance wrapping the primitive value, and updates the corresponding UTS spec to match the new semantics.

Changes:

• Mark RTPO8d as replaced and add RTPO8f to specify primitive → Instance wrapping the primitive.
• Update the UTS spec case to assert a primitive Instance is returned (anonymous id, value() exposes the primitive).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
specifications/objects-features.md	Deprecates the primitive-null clause and adds the primitive-wrapped Instance clause for PathObject#instance.
uts/objects/unit/path_object.md	Updates the primitive instance() UTS spec to assert an Instance is returned and behaves as a primitive instance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.