refactor(render,timeline,task): switch remaining handles to refcounted value structs

- oakrender: renderer/texture/frame/cache/colorprocessor/ticket/copier
  all become by-value {ctx, addref, release, abi_version} handles over a
  generic box; retain() folds into addref; new
  oakrender_cache_wrap_borrowed for native caches from oaknode
- oaktimeline: marker list/workarea borrowed handles become value
  handles (non-owning boxes) with explicit free
- oaktask: OakTaskTask becomes a value handle; ownership still moves
  to the manager on start (owns flag flips)
- consumers (timeline/task/codec sources) migrated; tests everywhere
  updated; suites green: render 45, timeline 117, task 106, node 96,
  common 193, codec 18, audio 36

include/render/cache.h

@@ -38,10 +38,13 @@ extern "C" {
  * @brief C ABI for the oakrender playback/frame-hash caches
  *        (olive::PlaybackCache / olive::FrameHashCache), M7 §2.2.
  *
- * An OakRenderCache IS a reinterpreted olive::FrameHashCache (created
- * without a parent node), no wrapper allocation. Handles from
- * oakrender_cache_create() are owned by the caller and must be released
- * with oakrender_cache_free().
+ * An OakRenderCache is a by-value reference-counted handle (shared_ptr
+ * semantics, see oakcommon's common/handle.h) boxing an
+ * olive::FrameHashCache (created without a parent node). Handles from
+ * oakrender_cache_create() are owned by the caller (reference count 1)
+ * and must be released with oakrender_cache_free(); handles from
+ * oakrender_cache_wrap_borrowed() are borrowed (release only frees the
+ * box).
  *
  * All timestamps are int64 frame numbers in the cache's timebase (see
  * oakrender_cache_set_timebase()); a cache without a valid timebase
@@ -51,27 +54,48 @@ extern "C" {
  * invalidate/validate are triggered by and known to the caller; the
  * facade re-emits notifications after the triggering command.
  */
-typedef struct OakRenderCache OakRenderCache;
+typedef struct OakRenderCache {
+	void *ctx; /**< Opaque pointer to the reference-counted object. */
+	void (*addref)(void *ctx); /**< Atomically increments the count. */
+	void (*release)(void *ctx); /**< Decrements the count, destroys at 0. */
+	uint32_t abi_version; /**< OAKRENDER_ABI_VERSION. */
+} OakRenderCache;
 
 /**
  * @brief Create a detached frame hash cache (no parent node, no
  * timebase). Owned by the caller.
  *
- * @return Cache handle, or NULL on allocation failure.
+ * @return Cache handle with reference count 1; ctx is NULL on
+ *         allocation failure.
  */
-OakRenderCache *oakrender_cache_create(void);
+OakRenderCache oakrender_cache_create(void);
 
-/** @brief Destroy a cache created by oakrender_cache_create(). NULL-safe. */
+/**
+ * @brief Release one reference to a cache created by
+ * oakrender_cache_create(). Convenience wrapper around
+ * cache->release(cache->ctx). NULL / empty-handle no-op; clears
+ * cache->ctx after releasing.
+ */
 void oakrender_cache_free(OakRenderCache *cache);
 
+/**
+ * @brief Borrowed handle wrapping a native frame cache pointer obtained
+ * through oaknode (oaknode_node_get_video_frame_cache()).
+ *
+ * The cache itself stays owned by its node: release() on this handle
+ * only frees the box. Empty handle (ctx == NULL) for a NULL native
+ * pointer.
+ */
+OakRenderCache oakrender_cache_wrap_borrowed(void *native_cache);
+
 /**
  * @brief Set the frame timebase used to interpret all timestamps of this
  * cache (FrameHashCache::set_timebase()).
  *
- * @return OAKRENDER_OK, or OAKRENDER_E_INVALID for NULL cache or
+ * @return OAKRENDER_OK, or OAKRENDER_E_INVALID for an empty cache or
  *         non-positive num/den.
  */
-int oakrender_cache_set_timebase(OakRenderCache *cache, int num, int den);
+int oakrender_cache_set_timebase(OakRenderCache cache, int num, int den);
 
 /**
  * @brief Set the cache UUID used in on-disk frame cache filenames
@@ -79,27 +103,27 @@ int oakrender_cache_set_timebase(OakRenderCache *cache, int num, int den);
  *
  * @return OAKRENDER_OK or OAKRENDER_E_INVALID.
  */
-int oakrender_cache_set_uuid(OakRenderCache *cache, const char *uuid);
+int oakrender_cache_set_uuid(OakRenderCache cache, const char *uuid);
 
 /**
  * @brief Mark the timestamp range [in_ts, out_ts) invalidated
- * (PlaybackCache::invalidate()). NULL cache is a no-op.
+ * (PlaybackCache::invalidate()). Empty cache is a no-op.
  */
-void oakrender_cache_invalidate(OakRenderCache *cache, int64_t in_ts,
+void oakrender_cache_invalidate(OakRenderCache cache, int64_t in_ts,
 								int64_t out_ts);
 
 /**
  * @brief Mark the timestamp range [in_ts, out_ts) validated
- * (PlaybackCache::validate()). NULL cache is a no-op.
+ * (PlaybackCache::validate()). Empty cache is a no-op.
  */
-void oakrender_cache_validate(OakRenderCache *cache, int64_t in_ts,
+void oakrender_cache_validate(OakRenderCache cache, int64_t in_ts,
 							  int64_t out_ts);
 
 /**
  * @brief 1 when the cache holds any validated range
- * (PlaybackCache::has_validated_ranges()), 0 otherwise / on NULL.
+ * (PlaybackCache::has_validated_ranges()), 0 otherwise / empty.
  */
-int oakrender_cache_has_validated_ranges(const OakRenderCache *cache);
+int oakrender_cache_has_validated_ranges(OakRenderCache cache);
 
 /**
  * @brief Timeline cache indicator height in pixels
@@ -117,7 +141,7 @@ int oakrender_cache_indicator_height(void);
  *
  * @return Range count (>= 0), or a negative OAKRENDER_E_* code.
  */
-int oakrender_cache_get_invalidated_ranges(OakRenderCache *c,
+int oakrender_cache_get_invalidated_ranges(OakRenderCache c,
 		int64_t in_num, int64_t in_den, int64_t out_num, int64_t out_den,
 		int64_t *ranges, int max_ranges);
 
@@ -130,20 +154,20 @@ int oakrender_cache_get_invalidated_ranges(OakRenderCache *c,
  * @param out_frame Receives an owned frame handle (release with
  *        oakrender_codec_frame_free()).
  *
- * @return OAKRENDER_OK, OAKRENDER_E_INVALID (NULL argument), or
+ * @return OAKRENDER_OK, OAKRENDER_E_INVALID (empty/NULL argument), or
  *         OAKRENDER_E_NOT_FOUND (no cached frame at `ts` / undecodable).
  */
-int oakrender_frame_cache_load(OakRenderCache *cache, const char *path,
+int oakrender_frame_cache_load(OakRenderCache cache, const char *path,
 							   const char *uuid, int64_t ts,
-							   OakCodecFrame **out_frame);
+							   OakCodecFrame *out_frame);
 
 /**
  * @brief Save a frame to the disk cache under the cache's timebase and
  * the frame's own timestamp (FrameHashCache::save_cache_frame()).
- * NULL arguments are a no-op.
+ * Empty/NULL arguments are a no-op.
  */
-void oakrender_frame_cache_save(OakRenderCache *cache, const char *path,
-								const char *uuid, const OakCodecFrame *frame);
+void oakrender_frame_cache_save(OakRenderCache cache, const char *path,
+								const char *uuid, OakCodecFrame frame);
 
 /* ---- Debug --------------------------------------------------------------- */