v1.10.1 — Per-environment ids block in page.meta.json + path-first pushPage

[PeterKnightDigital]

Stacked on top of #2 (v1.10.0). Base branch is cursor/page-assets-sync-2d5b. Merging this PR after #2 lands.

Summary

Closes the meta format gap that v1.10.0 explicitly deferred. Prior to v1.10.1, page.meta.json had a single top-level pageId slot:

• Pull from local first → meta.pageId = 1234 (local id).
• Re-pull from remote → meta.pageId silently switches to 5678 (remote id).
• Now pw_page_push calls $wire->pages->get($meta['pageId']) and addresses the wrong page on local. Or fails with "Page not found". Or — worst case — addresses an unrelated page that happened to have id 5678 locally.

The meta — your persistent record of the page — also had nowhere to record the local id and the remote id side by side, so an at-a-glance "which physical id corresponds to this page on each environment?" required re-resolving on both sides every time.

The format change

page.meta.json gains an ids block alongside the existing top-level pageId (kept as a back-compat mirror):

{
  "pageId": 1234,
  "canonicalPath": "/about/",
  "ids": {
    "local":  { "id": 1234, "lastSeenAt": "2026-04-30T15:00:00+00:00" },
    "remote": { "id": 5678, "lastSeenAt": "2026-04-30T15:30:00+00:00" }
  }
}

Each meta-write site populates only its own slot. The other side's slot is preserved verbatim. Five write paths cover every code route in / out of the meta:

• SyncManager::pullPage (local pull): writes ids.local, preserves any pre-existing ids.remote.
• SyncManager::exportPageYaml (remote-pull payload): emits ids.remote (from the receiver's perspective, this id IS the remote one — labelling it correctly at source means the receiver doesn't need to know which environment it pulled from).
• SyncManager::initPageMeta: writes ids.local for "linked" (existing page) scaffolds.
• SyncManager::publishPage: writes ids.local after the page is actually created on this site by a pw_page_publish writeback. Preserves any pre-existing ids.remote.
• SyncManager::pushPage writeback: refreshes ids.local after a successful save (lastSeenAt advances; new id recorded if it differs from the meta's last-seen).

Two more write paths handle the closing-the-loop case for remote pushes from the MCP side:

• MCP pushPage (mcp-server/src/pages/pusher.ts): after a successful live remote push, reads the pageId from the API response and writes ids.remote into the local meta. Best-effort, dry-run-aware, never fails the push.
• MCP publishPage remote branch: same recording for page:create responses.

And the critical merge fix on the puller side:

• MCP pullPageFromRemote (mcp-server/src/pages/puller.ts): merges the remote-emitted payload with any existing local meta — preserving ids.local, stripping any stray ids.local an older payload might include, and promoting legacy top-level pageId to ids.local for pre-v1.10.1 metas. Without this merge a pw_page_pull source: "remote" would still wipe the local id slot, defeating the whole point.

The pushPage refactor

This is the critical write-path change v1.10.0 deliberately deferred:

$page = $this->wire->pages->get($meta['canonicalPath']);
if ((!$page || !$page->id) && $localId) {
    $page = $this->wire->pages->get($localId);  // legacy fallback
}

$expected = $meta['ids']['local']['id'] ?? null;
if ($expected && $page->id !== $expected && !$force) {
    return [
        'error'         => "Path/id mismatch: meta last saw id $expected for $canonicalPath but it now resolves to id {$page->id} on this site.",
        'hint'          => 'Either the page was deleted and recreated, the slug was reused, or the meta is from a different site. Re-pull, or pass force:true to push to the new id anyway.',
        'expectedId'    => $expected,
        'currentId'     => (int) $page->id,
        'canonicalPath' => $canonicalPath,
    ];
}

• Lookup is path-first — same primary key the page-assets work in v1.10.0 already uses, applied uniformly to page content.
• Id is a sanity check, not a primary key. If the canonical path now resolves to a different id than the last-seen ids.local.id, the push is refused with a structured error pointing the operator at force:true. Catches: page deleted-and-recreated at the same path, slug rebound to an unrelated page, meta from a different site entirely.
• Legacy pageId is the fallback when a meta has no canonicalPath (covers older pulls and the rare moved-without-reconcile case).

getPageSyncStatus (powering pw_sync_status) and sync:reconcile are updated with the same path-first / id-fallback rule so all three read sites give identical results regardless of which side last wrote the meta. pw_sync_status results now also include the per-environment ids block when present.

Migration

Zero manual steps. Older page.meta.json files without the ids block keep working:

• readEnvId(meta, 'local') falls back to top-level pageId (the dominant historical case — almost every existing meta on disk was last written by a local pull).
• readEnvId(meta, 'remote') returns null for legacy metas — callers that need a remote id fall back to a path lookup, which is what the new code path does anyway.
• The first write to the meta on v1.10.1+ adds the ids block.
• Remote pulls promote any pre-existing top-level pageId to ids.local before merging in the remote payload.

Any caller that was passing a now-misaddressed meta.pageId and getting "Page not found" will instead get a successful path-based resolution OR a clear id-mismatch diagnostic — both improvements over the silent breakage they were getting before.

Validation

• 16 reflection-driven PHP tests covering the new helpers:
  • buildIdsBlock: fresh writes, preserve other side, defensive bad env names, key-stable output for byte-identical writes.
  • readEnvId: new format, legacy fallback for local, null for remote when only legacy data exists, malformed / empty / zero inputs.
• 9 Node tests covering the TS merge logic in pullPageFromRemote:
  • No-existing-meta passes payload through.
  • Existing v1.10.1 ids.local is preserved across the merge.
  • Legacy top-level pageId is promoted to ids.local.
  • Stray payload ids.local is stripped (defensive).
  • No-local-available case leaves ids.local absent rather than guessing.
• npm run build (TypeScript strict) passes.
• php -l clean on every modified PHP file.

All 25 tests pass.

Files changed

• src/Sync/SyncManager.php — new buildIdsBlock / readEnvId helpers; pullPage, exportPageYaml, initPageMeta, publishPage and pushPage writes wired through them; pushPage lookup refactored to path-first with id verification; getPageSyncStatus and sync:reconcile updated to the same rule.
• mcp-server/src/pages/puller.ts — pullPageFromRemote now merges existing meta with the remote payload (preserves ids.local, strips stray local from payload, promotes legacy pageId).
• mcp-server/src/pages/pusher.ts — pushPage and publishPage now record ids.remote in the local meta after a successful live remote operation, via a new recordRemoteIdInMeta() helper.
• src/Cli/CommandRouter.php, mcp-server/src/index.ts, PromptWire.module.php, mcp-server/package.json — version bump 1.10.0 → 1.10.1.
• CHANGELOG.md, ROADMAP.md — release entry; the deferred section that lived inside the v1.10.0 entry has been removed (replaced by this release).