Align path-based LiveObjects API spec with ably-js implementation

[sacOO7]

• Based on [AIT-30] LiveObjects Path-based API spec #427, check [AIT-30] LiveObjects Path-based API spec #427 (comment)

Summary

Cross-validation against ably-js commit 3deeee8e surfaced multiple gaps between the path-based LiveObjects API spec and the implementation. This PR applies every spec change that doesn't already live in an in-flight PR on this repo.

Scope is deliberately limited to non-PR-delegated items. Three upstream PRs already cover the BatchContext, implicit-attach, and REST API surfaces, and review comments have been posted there with the corresponding spec gaps; this PR doesn't duplicate that work.

Major additions

• Path event semantics — RTO24c–RTO24e: bubbling vs non-bubbling dispatch rules; identity-change non-bubbling event when a parent MAP_SET overwrites a subscribed path.
• Multi-parent reference graph — RTLO3f, RTLO3g, RTO5c10: parentReferences map maintained on every map mutation, getFullPaths returns all distinct root-to-object paths (cycle-safe), pool rebuild after a sync sequence.
• Tombstone auto-deregistration — RTLO4b8–RTLO4b10: instance listeners receive the tombstone update, then are deregistered; path subscriptions unaffected; listener errors caught and logged per ably-js EventEmitter.callListener.
• Raw LiveMap/LiveCounter rejection — RTLM20e8: validation rejects raw live-object references in MAP_SET; RTLM20e1 marked replaced.
• PathObject#unsubscribe / Instance#unsubscribe removed — RTPO20, RTINS17 marked deleted; deregistration is exclusively via Subscription.unsubscribe() (matches impl).

Validation tightening

• Channel-mode + state + echo checks at every PathObject/Instance write wrapper (RTPO15e–RTPO18e, RTINS12d–RTINS15d) and subscribe wrapper (RTPO19i, RTINS16i, RTPO19h).
• at() path-string type check (RTPO6e).
• Instance#get conditional key-type check (RTINS5d).
• subscribeIterator cancellation contract (RTPO21d, RTINS18d).
• amount validation on increment/decrement wrappers (RTPO17f/18f, RTINS14e/15e).
• LiveMap value-type entries null rejection (RTLMV4c rewritten).
• LiveCounter value-type defaulting simplified (RTLCV4a/b1).

Editorial / non-normative additions

• Compact memoisation broadened (RTPO13b5, RTPO14a2): cyclic OR shared reference dedup.
• LiveMap value-type immutability scope clarified (RTLMV3d): shallow only.
• Brand-equivalent return types on LiveMap.create / LiveCounter.create (RTLMV3e, RTLCV3e).
• Listener ordering and duplicate-subscription independence (RTO24f/g).
• Subscription idempotency (SUB2b in features.md).
• RTPO6f path edge cases (empty segment, empty middle segment, trailing backslash, at(p.path()) round-trip).
• RTLMV4l/m/n: validation-error order, parallelisable server-time fetches, Number type scope (BigInt-equivalent optional).
• RTO23e: typed channel.object.get<T>() usage hint.

Spec hygiene

• RTO11/RTO12 deprecation cross-references remapped from umbrella RTLMV3/RTLCV3 to specific sub-clauses (e.g. RTO11f14a → RTLMV4e1, RTO12f7 → RTLCV4g1); post-publish-lookup sub-clauses (RTO11g/h/i, RTO12g/h/i) marked deleted because the wrap-result-as-LiveObject semantics no longer apply.
• RFC 2119: lowercase should → MUST on new-in-branch validation clauses (RTLMV4a/b, RTLCV4a).
• IDL: named type aliases (Primitive, LiveObjectType, Value, ObjectIdReference); internal count/entries fields on value types; unsubscribe lines removed from PathObject/Instance.

Out of scope (delegated to upstream PRs)

These items were intentionally NOT applied locally because in-flight PRs already cover them. Review comments with detailed cross-references to ably-js are posted on each:

Concern	Upstream PR	Review comment
BatchContext spec + batch() on PathObject/Instance	#471	Initial + follow-up
Implicit attach on RealtimeObject#get	#472	Comment
REST objects API	#476	Comment

Also out of scope:

• ably-js code changes (raw LiveMap/Counter rejection in validateKeyValue, cheapRandStr → randomString for nonces, depth-validation tightening). Will be raised separately in ably-js.
• api-docstrings.md rewrites — deferred to a follow-up PR (large editorial task).

Verification

• (cd build && npm run lint) → ✓ no duplicate IDs across all three spec files.
• Every applied clause cross-checked against ably-js src/plugins/liveobjects/ at commit 3deeee8e.

Test plan

• Reviewer spot-checks 3–5 applied clauses against ably-js source.
• CI lint passes on the PR.
• Hugo render check (no flat list-item artefacts in deprecation blocks).
• Confirm the three out-of-scope PRs land separately with their own review comments addressed.

🤖 Generated with Claude Code

[lawrence-forooghian]

I'm a bit confused by this (and similar ones here); if we're already delegating to LiveCounter#increment then why would we need to re-perform its checks?

[lawrence-forooghian]

Would this not be better off in the UTS?

[lawrence-forooghian]

I'm holding off on reviewing this until you've reviewed it yourself but at a glance it seems like it would definitely benefit from you looking through it and deciding what actually needs changing

[lawrence-forooghian]

The stuff to do with bubbles and parentReferences seems like it might genuinely be necessary because it sounds like core logic (and when I looked at the base PR I didn't fully understand the logic too, see my comments there); I'd suggest focussing on that first

[lawrence-forooghian]

Would you mind taking a look at my comments on #427 to see whether there's any overlap with your changes here please?

[sacOO7]

Would you mind taking a look at my comments on #427 to see whether there's any overlap with your changes here please?

Sure, going through liveobject spec PRs to better understand existing context and avoid relevant duplications