# Phase 11: Company, Catalog & Subscription Sync - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-07-10
**Phase:** 11-company-catalog-subscription-sync
**Areas discussed:** Product catalog scope, Subscription cost fields, Stale/removed entity handling, Sync strategy (full vs incremental)

---

## Product Catalog Scope

| Option | Description | Selected |
|--------|-------------|----------|
| Full catalog sync | Fetch and store PAX8's complete product catalog every sync, independent of subscriptions | |
| Lazy/referenced-only | Only fetch/store catalog entries for SKUs referenced by a synced subscription | ✓ |
| You decide | Let planner choose based on PAX8's actual catalog API shape | |

**User's choice:** Lazy/referenced-only
**Notes:** Directly carries forward the gray area left open in Phase 10's CONTEXT.md discretion section.

| Option | Description | Selected |
|--------|-------------|----------|
| Fetch it inline during the same sync run | Call PAX8's product-detail endpoint immediately when an unrecognized SKU is hit | ✓ |
| Two-pass sync | First pass collects referenced product IDs, second pass batch-fetches them | |

**User's choice:** Fetch it inline during the same sync run

---

## Subscription Cost Fields

| Option | Description | Selected |
|--------|-------------|----------|
| Your partner/reseller cost only | Store only what PAX8 bills the reseller | |
| List price + partner cost, both | Store both as separate columns, if PAX8 exposes both | ✓ |
| Whatever PAX8's subscription endpoint returns, typed generically | Don't presuppose the pricing model | |

**User's choice:** List price + partner cost, both
**Notes:** Ties directly to SEED-002's stated margin/profitability reconciliation goal.

| Option | Description | Selected |
|--------|-------------|----------|
| Store as-is, normalize at read time | Keep raw per-billing-period amount; monthly-equivalent math happens later | ✓ |
| Normalize to monthly at sync time | Compute and store a monthly-equivalent column at sync time | |

**User's choice:** Store as-is, normalize at read time

---

## Stale/Removed Entity Handling

| Option | Description | Selected |
|--------|-------------|----------|
| Soft-delete (is_deleted flag) | Mark is_deleted=true, deleted_at=now() instead of removing | ✓ |
| Leave rows as-is (no tracking) | Don't track removal this phase | |

**User's choice:** Soft-delete (is_deleted flag)
**Notes:** Matches existing Pulse audit-column convention.

| Option | Description | Selected |
|--------|-------------|----------|
| Companies + subscriptions only | Catalog stays as historical reference, never soft-deleted | |
| All three tables consistently | Apply is_deleted/deleted_at to pax8_products too | ✓ |

**User's choice:** All three tables consistently

---

## Sync Strategy (Full vs Incremental)

| Option | Description | Selected |
|--------|-------------|----------|
| Full resync every run | Fetch and upsert everything each sync, no last-sync tracking | |
| Incremental where PAX8 supports it | Follow entity-sync.ts pattern; modified-since filter, fall back to full if unsupported | ✓ |
| You decide | Let planner/researcher decide after seeing PAX8's actual API | |

**User's choice:** Incremental where PAX8 supports it

**Follow-up tension surfaced:** Incremental sync alone can't detect entities PAX8 stops returning (no signal that something is now missing), which conflicts with the soft-delete decision above.

| Option | Description | Selected |
|--------|-------------|----------|
| Periodic full reconciliation pass | Incremental for routine updates + periodic full ID-listing diff to catch removals | ✓ |
| Full sync only for existence, incremental for details | Always fetch full ID list, but incremental-fetch only changed record details | |

**User's choice:** Periodic full reconciliation pass

---

## Claude's Discretion

- **Reconciliation-pass cadence** — whether the full-ID reconciliation pass runs every sync invocation or on a separate schedule, informed by whatever trigger mechanism this phase builds (Phase 13 owns actual cron wiring).
- **Missing partner-cost field fallback** — if PAX8's API doesn't expose partner cost distinctly from list price, planner decides the fallback column shape.

## Deferred Ideas

None — discussion stayed within phase scope.
