type: meta

slug: platform-modules-migration

topic: Migrate zync.is onto @platform-modules/* (codex seat)

exec_mode: ship

scheduler: dag-parallel

seat: codex

land_mode: pr

base_branch: master

gate0_cmd: pnpm install --prefer-offline --silent && pnpm -C apps/zync-api exec vitest run --passWithNoTests src/integrations/platform

status_enum: BLOCKED PENDING WORKING WRITTEN REVIEWED COMMITTED

truth_rule: this file is ground truth for INTENT; git is ground truth for DONE-NESS — reconcile statuses against git, never trust a COMMITTED line with no commit

refresh_how: native Read of THIS file

refresh_what: meta + every goal/methodology/intent/direction record + all WORKING and BLOCKED tasks

refresh_when:
wave/phase boundary
any task status change
after a compaction system-reminder
before calling advisor

update_rule: on status change, rewrite that task's single line in place

report_rule: at session end emit brief: done / blocked / deferred / canceled


type: goal

text: Replace hand-rolled @zync/* code with embedded @platform-modules/* per the 3-tier disposition (embed-direct / substrate+keep / defer), pilot-first, edit existing specs not create new. Hardening deferred.


type: methodology

text: Per-task: codex (cx-implement.sh) embeds module in worktree + writes a parity/equivalence test that IMPORTS the real host symbol (never reconstructs it) + makes acceptance green; codex review (cx.sh) + gate0 + opus/security-guard floor gate each task; integrate on branch plan/<slug>; land via PR (human merges). Expand/contract schema (forward-only) for Axis-B owners; migrations authored in worktree, applied to prod ONLY at ship.


type: intent

text: Stop maintaining divergent forks of generic capability; consume the platform substrate so fixes/features flow once. Upstream zync's richer-but-generic pieces (scheduleValueAt, IL VAT dataset, generic CoA) back to platform rather than fork them.


type: direction

verbatim: use all seats from anthropic models, no codex/cursor


verbatim: No cursor, but YES codex. use codex for all the seats relevant


verbatim: ca.sh should not be used in this workflow at all


verbatim: you should change the existing specs, not make new specs. only make the new plan for this refactor


verbatim: hardening may be later after its done


type: gated

category: architecture

needs: Pilot waves (seo/ai/uploads/tax-vat-math) embedded + gated. Proceed to the full L0–L3 migration?

why: Pilot-first: prove the codex-seat embed+swap-parity pattern produces clean, gate-passing modules before committing the larger waves. User chose pilot-first.

status: OPEN

source: author


category: irreversible

needs: Final integration is green through L3. Author the expand/contract migration files in-worktree and OPEN the migration PR (land_mode=pr)? The run authors migrations + opens the PR only — it does NOT apply migrations to prod or redeploy workers.

why: Last checkpoint before the run opens a PR that PROPOSES a live-prod schema cutover. The run itself stays reversible (worktree + PR). The irreversible prod apply (Neon zync-prod schema + worker redeploy) is the SEPARATE post-merge deploy, human/CI gated — never performed by this unattended run.

blast_radius: In-run: PR open only, no prod DB write, no worker redeploy. Post-merge (out of run scope): Neon zync-prod behind Hyperdrive forward-only expand + both Cloudflare Workers; production money-adjacent.


type: task

desc: T0 worktree+vehicle bootstrap: wire @platform-modules/* into zync pnpm via file: deps; lockfile; pnpm install green. See plan Task 0.

status: PENDING


desc: T1 seo — VERIFIED no hand-rolled JSON-LD/sitemap host code in zync → run Step-1 Gate-0b; expected NO-EMBED (nothing to swap), mark no-embed and skip. Pilot exemplar role moves to uploads(T3)/ai(T2)/tax(T4). See plan Task 1 verified note.


desc: T2 embed ai (Axis D) — adopt @platform-modules/ai provider seam behind zync's adapter; parity test IMPORTS zync's real adapter and asserts equivalence on a fixed prompt/tool path. See plan Task 2.


desc: T3 embed uploads (Axis A,D) — adopt @platform-modules/uploads magic-bytes/image-dimensions/presign; parity test IMPORTS zync's real magic-byte guard + presign and asserts byte-equal classification + presign params. See plan Task 3.


desc: T4 embed tax/vat-math (Tier-2 pure import) — adopt generic vat-math primitive; IL statutory rates stay host; parity test IMPORTS zync's real VAT calc and asserts equivalence across the IL rate table. See plan Task 4.


desc: T5 pilot registration + GATE: wire pilot embeds into apps/zync-api/src/index.ts; full pilot build/e2e green. PILOT CHECKPOINT.

requires_decision: g-pilot

blocker: user decision g-pilot: proceed to full migration after reviewing pilot


desc: T6 embed util (L0) — swap host util call-sites to @platform-modules/util; parity test imports both. See plan Task 6.


desc: T7 embed db driver (L0) — adopt @platform-modules/db driver internals behind @zync/db; no schema change. See plan Task 7.


desc: T8 i18n Gate-0b (L0) — clear Gate-0b: i18n is Astro-native; if it cannot embed cleanly mark NO-EMBED and document. See plan Task 8.


desc: T9 embed mail (L1) — adopt @platform-modules/mail send seam behind host adapter; equivalence test. See plan Task 9.


desc: T10 embed jobs (L1 — Axis A,B,C,D) — FIRST Axis-B schema owner: expand/contract jobs schema + host-injected IdempotencyStore (Axis C, enumerate-faithful). Migration authored in worktree, applied at ship. See plan Task 10.


desc: T11 L1 registration — wire mail+jobs into index.ts; build/e2e green.


desc: T12 embed tenancy (L1 sec — Axis A,B,C) SECURITY-CRITICAL: Gate-0b rbac (triad vs host field-perm — may split); expand/contract tenancy schema + TenancyStore (Axis C). Cross-model review MANDATORY (codex writes → opus/security-guard floor). See plan Task 12.


desc: T13 embed auth hash substrate (L1 sec — Tier-2): password-hash primitive ONLY inside PasswordHashDO; rehash-on-login; keep host session/oauth/2fa/portal-sessions. roundtrip+cross-verify test (existing zync hash verifies via module engine). See plan Task 13 + hash-parity hazard block.


desc: T14 embed audit (L2 — Axis A,B) — expand/contract audit-log schema. See plan Task 14.


desc: T15 embed notifications (L2 — Axis A,C,D, host tables) — PreferenceStore+DedupStore (Axis C); host owns tables. See plan Task 15.


desc: T16 embed realtime/server (L2 — Axis A,F) — embed /server export (core is types-only). See plan Task 16.


desc: T17 embed search (L2 — Axis A, host tables) — host owns tables, embed query primitives. See plan Task 17.


desc: T18 L2 registration — wire audit/notifications/realtime/search into index.ts; build/e2e green.


desc: T19 embed helpdesk (L3 — Axis A,B) — expand/contract helpdesk schema. See plan Task 19.


desc: T20 embed marketing (L3 — Axis A,C,D, host tables) — ComplianceStore+SelfManagedStore (Axis C); host tables. See plan Task 20.


desc: T21 L3 registration — wire helpdesk/marketing into index.ts; build/e2e green.


desc: T22 final integration green + author migrations + open PR: ensure plan/<slug> builds + full e2e green in-worktree; author ALL expand/contract migration files in-worktree (NOT applied). Engine Ship phase opens the migration PR (land_mode=pr). This run performs NO prod DB write and NO worker redeploy — prod schema apply happens POST-MERGE at deploy, human/CI gated. See plan Task 22.

requires_decision: g-ship

blocker: user decision g-ship: open migration PR (no in-run prod write)


type: deferred

text: T23 scheduleValueAt<T>, T24 IL VAT dataset 1976–2025, T25 generic Chart-of-Accounts — PLATFORM-REPO upstream track (/home/user/Projects/platform). Different repo → NOT executable by this single-repo run. Run separately via platform-extract-modules. Gates Tier-2 full rate-resolution only; T4 proceeds with host IL rates now.

reason: cross-repo; this run's repoRoot is zync.is


note: seo pilot was mis-specified in the original plan markdown (assumed a hostBuildJsonLd that does not exist). Corrected to greenfield-adopt in T1 desc; plan markdown Task 1 also corrected. ALL parity tasks: contract MUST force importing the real host symbol, never reconstructing it (codex reconstructed in the seat-probe).


note: Engine: codex seat lives in ~/.claude/workflows/run-plan.js behind meta.seat==='codex' (implementCodex + fixCodex via cx-implement.sh; classify skipped; no cursor/north, no fallback). Review/integrate/commit already codex (cx.sh/cc.sh). opus/security-guard floor still runs on HIGH/trust-boundary reviews → preserves cross-model independence on T12/T13.