[5PK]

Problem

getContentItemTypes sorted content into two tiers: normal and linked. Every item another item references went into one linked tier, pushed as one batch (batchSize 250) in reversed insertion order. In a chain like FeaturedPost → Post → Category, Post and Category are both linked and land in the same batch. The batch processor checks each item's references before the batch writes, so Post fails with Unresolved content reference(s) not present in the target mapping, and FeaturedPost fails because Post never got created. Category is created moments later in the same run. A re-sync "fixes" it by accident because Category exists by then, which is why it can look intermittent.

The sync permutation test (PROD-3016) reproduces this every run: Blog Starter into an empty instance gives 3 posts and 2 featured posts failed, verify differences, and a re-sync that still plans 6 creates.

Fix

• get-content-item-types.ts: also returns linkedContentLevels, the linked items split into dependency levels, leaves first. A level's items reference only lower levels.
  • It builds a graph from the existing collectReferencedContentIDs (whole-list and single-item references, including companion fields), keeping only edges between linked items and dropping self-references.
  • Tarjan's algorithm collapses cycles. Each item sits one level above its deepest dependency, so this works for any depth, uneven depths and diamonds. It is iterative, so a long chain can't overflow the stack.
  • linkedContentItems is unchanged.
• content-pusher.ts:
  • The linked tier is still filtered once. It is then grouped by level, and each level goes through its own processBatches call (Linked Content (level n/N)), so every mapping a level needs was written by an earlier level.
  • .reverse() is removed.
  • A level the filter emptied is skipped, so there is no empty processBatches call any more.
  • The duplicated result bookkeeping for the two tiers is now one recordBatchResult helper.
  • Preflight is unchanged.

Cycles: handled by the two-pass push below (PROD-3076).

Cost: each level is one more batch round trip, so deep chains take longer than a single batch. Depth comes from the content model, not the amount of content.

Also: empty page titles (found by the live test once linked content synced)

processPage sent page.title || page.menuText || page.name, so an untitled page reached the target titled with its name. A dynamic page's titles come from its titleFormula, so it is often untitled in the source. Blog Starter's posts-dynamic page is one, and verify reported posts-dynamic / title on every sync. Pulled pages come through the Content Sync SDK (the Fetch API), which returns an empty title as null, so "untitled" arrives as null, not "".

The Management API's PageItem.title is optional, the batch insert copies it without validating it, and the server stores a null title as "". There was never a reason to fill one in. The title is now sent as-is, with null as "".

Verified locally: a sync of a leased blog copy into a leased blank instance, then verify passes (0 failures) and sync --preflight plans nothing.

Tests: process-page.test.ts covers a null title on a dynamic page (fails without the fix), an empty title, a normal title, and no fallback to menu text or name.

Also: content in a reference cycle (PROD-3076)

Items that reference each other by content ID (A -> B -> A), or that reference themselves, were never created. Each failed the unresolved-reference check because the other had no target ID yet, and every later sync failed the same way. Dependency levels can't help, since a cycle has no leaf. Models already solve this with stub-then-fields (model-pusher.ts), and content now does the equivalent in the same run:

• getContentItemTypes also returns linkedCycleReferences: for each linked item in a cycle, its by-ID references into that cycle, including a self-reference. Whole-list references resolve by container name, never block, and aren't included.
• Pass 1: for each level, a cycle member whose partners have no mapping yet goes out with those references blanked (stripContentReferences: contentid set to -1, the ID removed from sortids and from companion fields).
• Pass 2: right after, the same members go out in full (Linked Content …: completing reference cycles). They go through a batch processor with the new trustSameRunMappings option, so the update targets the item pass 1 created. That item isn't in the pulled target yet, and without the option it would look deleted and be created again.
• Each item is counted and published once, from pass 2. A failed pass 2 is reported, and ContentItemMapper.markSourceChanged makes the next sync push the item again. A cycle whose members are already mapped (a re-sync) goes out once, unchanged.
• The server accepts a required linked-content field saved blank (tested on dev), so pass 1 works for required fields.

Verified on dev with a leased blog copy plus a CycleNode model (A <-> B, C -> C, a required single-item linked field with a companion field). A first sync into an empty instance creates all 30 items with 0 failures, the references point at the right target IDs, verify passes, and a re-sync plans nothing. The live test now seeds the same kind of cycle into its source (see below).

Tests: strip-content-references.test.ts (new), cycle detection in get-content-item-types.test.ts, trustSameRunMappings in content-batch-processor.test.ts, and the two passes, counts, publishing, failed pass 2, failed stub and re-sync in content-pusher-linked-levels.test.ts.

Tests

• get-content-item-types.test.ts:
  • a three-deep chain
  • a 50-deep chain (one level per item, no stack issues)
  • uneven depths
  • a diamond
  • whole-list references
  • a cycle above a leaf
  • a self-reference
  • levels covering exactly the linked items
• New content-pusher-linked-levels.test.ts:
  • one processBatches call per level, in order, then the normal tier
  • totals and failure registration across levels
  • a level emptied by the filter
  • preflight
  • splitIntoLevels
• content-pusher-validation.test.ts: no longer expects a processBatches call for an emptied linked tier.
• Full suite: 136 suites, 2,594 tests pass; npm run build passes.

Live verification

The live sync test (#251, now on main) runs on this PR. It includes a reference-cycle fixture: A ↔ B and a self-reference through a required linked field with a companion field. After the first sync, its cycles check confirms each copy points at its partner's target ID. That check, together with round 0's sync, verify and no-op checks, is what this PR fixes. The later change rounds (both-direction edits, drift, conflicts) have failures of their own that happen with main's CLI too (see #251).

🤖 Generated with Claude Code

[5PK]

Closing: everything here is in #254 (release/1.3.0-beta.0), which takes these changes to main for the 1.3.0 beta. This branch has no commits that #254 doesn't. The description and review threads here still apply.

🤖 Generated with Claude Code