feat(safePushData): detailed error reporting and result tracking (#4)

* safePushData: log which fields failed on each retry round

Each failing round now reports the set of offending field paths (with the
AJV keyword) instead of just an item count, split into fields we repaired
and fields that forced a drop. The give-up log lists the fields still
failing.

The set is intentionally not a per-item breakdown: one bad field usually
appears on many items in a batch, and array indices collapse into `/tags/[]`
for the same reason. The list is capped at 20 entries with the overflow
counted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ek1iV9QVKioLZ3EiL4cPYc

* safePushData: return pushFn's result, rename result fields, fix repair logic

BREAKING: the result shape now names what it holds — `pushed` -> `pushedCount`,
`dropped` -> `droppedItems`, `attempts` -> `attemptCount`. `*Count` is a
number, `*Items` is an array of objects.

Whatever `pushFn` resolves to is handed back as `pushResult` (the successful
call's value; absent when every item was dropped). `PushFn<T, R>` and
`SafePushDataResult<T, R>` carry the type through.

Logic fixes found while reviewing:

- Hitting the attempt cap used to drop the *entire* remaining batch, including
  items the API never complained about — the exact data loss this wrapper
  exists to prevent. Now only the items still failing are dropped and the
  survivors get one final push of their own.
- Sibling array elements were spliced front-to-back, so the second `/tags/N`
  path pointed at a shifted array: a valid element could be deleted while the
  invalid one stayed. Errors are now applied deepest- and highest-index-first.
- A nested `required` deleted the whole parent object; it now gets the same
  placeholder treatment as a root-level one, at any depth.
- An item whose errors are all unactionable (paths it doesn't have) was
  re-pushed unchanged until the cap, burning every attempt for the rest of the
  batch. It's dropped on the spot instead.
- Give-up drops reported stale errors from an earlier round; the per-item
  errors are now reset each round, so they say why the item is failing *now*.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ek1iV9QVKioLZ3EiL4cPYc

* safePushData: broaden the test suite to 53 cases

Covers the gaps left by the previous round: additionalProperties at the root
and nested, mixed error kinds in a single round, JSON Pointer escaping on
placeholder paths, per-item state surviving a splice, dropped items reporting
the caller's original, non-object items, invalid items the API sends no errors
for, the salvage push (its pushResult, its rejection, non-schema errors from
it), maxAttempts: 1, the guard's negative cases, log label formatting, and an
end-to-end mixed batch.

Each of the five logic fixes was mutation-checked: reverting the repair
ordering, the pointer escaping, the salvage push, the no-progress drop, or the
nested `required` handling makes the corresponding tests fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ek1iV9QVKioLZ3EiL4cPYc

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: metalwarrior665

README.md

@@ -17,13 +17,20 @@ await Actor.init();
 const result = await safePushData((batch) => Actor.pushData(batch), items);
 
 console.log(result);
-// { pushed: 2, dropped: [...], attempts: 2 }
+// { pushedCount: 2, droppedItems: [...], attemptCount: 2, pushResult: undefined }
 ```
 
 Accepts a single item or an array. `pushFn` is the first positional arg
 and is required — the library itself never imports the Apify SDK, and a
 CI check forbids `.pushData(` from appearing anywhere in the source.
 
+Whatever `pushFn` resolves to comes back as `pushResult`, so a push
+function with a meaningful return value stays usable:
+
+```ts
+const { pushResult } = await safePushData((batch) => client.dataset(id).pushItems(batch), items);
+```
+
 ## Performance notes
 
 The happy path is a single `try/await pushFn(items)` with **no extra
@@ -38,11 +45,12 @@ every AJV error per item:
 
 | Error                                | Action                                                                             |
 | ------------------------------------ | ---------------------------------------------------------------------------------- |
-| `required` at the root               | Set the missing field to `null` and mark the path as a placeholder.                |
-| `additionalProperties` at the root   | Delete the unknown property.                                                       |
+| `required` (at any depth)            | Set the missing field to `null` and mark the path as a placeholder.                |
+| `additionalProperties` (any depth)   | Delete the unknown property.                                                       |
 | `type` / `format` / etc. at the root | Item itself is the wrong shape → dropped.                                          |
 | Constraint on a **placeholder** path | Replace with a type-aware default (see below). If no default is known → dropped.   |
 | Constraint on **user-supplied** data | Delete the field. If the schema later marks it required, a placeholder takes over. |
+| Nothing on the item was actionable   | Item is dropped — an unchanged item would fail identically on the next push.       |
 
 ### Placeholder defaults
 
@@ -73,19 +81,52 @@ The retry loop chases one layer of errors per round
 (`required` → `type` → push) until either the push succeeds
 or `maxAttempts` (default 5) is hit.
 
+### When the attempt cap is hit
+
+Items still failing on the last allowed attempt are dropped — but the rest
+of the batch is **not** lost with them. Because a rejected push stores
+nothing at all, the wrapper drops the incurable items and then makes one
+final push with the survivors, which the API already validated in the
+previous round. That final push is counted in `attemptCount`, so a run that
+exhausts `maxAttempts: 5` can report `attemptCount: 6`.
+
+## Logging
+
+Every failed round logs which fields went wrong, so you can fix the schema
+(or the scraper) without digging through the returned `droppedItems`:
+
+```
+safePushData: schema validation failed on attempt 1: 12 invalid item(s); repaired fields: /age (type), /name (required), /tags/[] (type); dropped 2 item(s) on unfixable fields: /email (format); retrying with 10 item(s).
+safePushData: gave up after 5 attempts; dropped 3 item(s) still failing on fields: /sku (pattern); pushing the 9 valid item(s) left.
+```
+
+The field list is a **set**, not a per-item breakdown — one bad field
+usually shows up on many items in a batch, and knowing which item had which
+problem rarely changes what you do about it. Array indices collapse
+(`/tags/0`, `/tags/7` → `/tags/[]`) for the same reason, and the list is
+capped at 20 entries with the rest reported as `(+N more)`.
+
 ## Options
 
-| Option        | Type     | Default | Notes                |
-| ------------- | -------- | ------- | -------------------- |
-| `maxAttempts` | `number` | `5`     | Hard cap on retries. |
+| Option        | Type     | Default | Notes                                                          |
+| ------------- | -------- | ------- | -------------------------------------------------------------- |
+| `maxAttempts` | `number` | `5`     | Cap on repair rounds, plus the final salvage push if it's hit. |
 
 ## Return shape
 
+Names say what they hold: `*Count` is a number, `*Items` is an array of
+objects.
+
 ```ts
-interface SafePushDataResult<T> {
-    pushed: number;
-    dropped: { item: T; errors: ValidationError[] }[];
-    attempts: number;
+interface SafePushDataResult<T, R = unknown> {
+    /** How many of the caller's items made it into the dataset. */
+    pushedCount: number;
+    /** The items we couldn't repair, each with the errors that doomed it. */
+    droppedItems: { item: T; errors: ValidationError[] }[];
+    /** How many times `pushFn` was actually called. */
+    attemptCount: number;
+    /** What the successful `pushFn` call resolved to; absent if none did. */
+    pushResult?: R;
 }
 ```