feat: add sync snapshot — single-call pull for Apple clients (276 tests)

Author: pH-7

CortexOSApp/Shared/Models/DecisionResult.swift

@@ -57,3 +57,43 @@ extension DecisionResult {
     /// Whether this item contradicts a prior assumption.
     var isContradiction: Bool { contradictionOrConfirmation == "contradicts" }
 }
+
+// MARK: - Context mutation requests
+
+struct DecisionCreateRequest: Codable {
+    let decision: String
+    let reason: String
+    var project: String = ""
+    var assumptions: [String] = []
+}
+
+struct OutcomeCreateRequest: Codable {
+    let decisionId: String
+    let outcome: String
+    var impactScore: Double = 0.0
+
+    enum CodingKeys: String, CodingKey {
+        case outcome
+        case decisionId = "decision_id"
+        case impactScore = "impact_score"
+    }
+}
+
+struct InsightCreateRequest: Codable {
+    let title: String
+    var summary: String = ""
+    var whyItMatters: String = ""
+    var architecturalImplication: String = ""
+    var nextAction: String = ""
+    var confidence: Double = 0.5
+    var tags: [String] = []
+    var relatedProject: String = ""
+
+    enum CodingKeys: String, CodingKey {
+        case title, summary, confidence, tags
+        case whyItMatters = "why_it_matters"
+        case architecturalImplication = "architectural_implication"
+        case nextAction = "next_action"
+        case relatedProject = "related_project"
+    }
+}

CortexOSApp/Shared/Models/SyncSnapshot.swift

@@ -0,0 +1,182 @@
+//
+//  SyncSnapshot.swift
+//  CortexOS
+//
+//  Single-call sync model — everything a client needs in one pull.
+//  Backend is source of truth. Clients decode this on launch.
+//
+
+import Foundation
+
+// MARK: - Snapshot
+
+struct SyncSnapshot: Codable {
+    let profile: SyncProfile
+    let activeProject: ProjectContext?
+    let priorities: PriorityBrief?
+    let recentDecisions: [SyncDecision]
+    let insights: [SyncInsight]
+    let signals: [SyncSignal]
+    let workingMemory: SyncWorkingMemory
+    let syncedAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case profile, priorities, insights, signals
+        case activeProject = "active_project"
+        case recentDecisions = "recent_decisions"
+        case workingMemory = "working_memory"
+        case syncedAt = "synced_at"
+    }
+}
+
+// MARK: - Profile (subset for sync)
+
+struct SyncProfile: Codable {
+    let name: String
+    let role: String
+    let goals: [String]
+    let interests: [String]
+    let currentProjects: [String]
+    let ignoredTopics: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case name, role, goals, interests
+        case currentProjects = "current_projects"
+        case ignoredTopics = "ignored_topics"
+    }
+}
+
+// MARK: - Project
+
+struct ProjectContext: Codable {
+    let projectName: String
+    let currentMilestone: String
+    let activeBlockers: [String]
+    let recentDecisions: [String]
+    let architectureNotes: [String]
+    let openQuestions: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case projectName = "project_name"
+        case currentMilestone = "current_milestone"
+        case activeBlockers = "active_blockers"
+        case recentDecisions = "recent_decisions"
+        case architectureNotes = "architecture_notes"
+        case openQuestions = "open_questions"
+    }
+}
+
+// MARK: - Priority Brief
+
+struct SyncPriority: Codable, Identifiable {
+    var id: String { title }
+    let rank: Int
+    let title: String
+    let whyItMatters: String
+    let nextStep: String
+    let source: String
+    let relevanceScore: Double
+    let tags: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case rank, title, source, tags
+        case whyItMatters = "why_it_matters"
+        case nextStep = "next_step"
+        case relevanceScore = "relevance_score"
+    }
+}
+
+struct PriorityBrief: Codable {
+    let date: String
+    let priorities: [SyncPriority]
+    let ignored: [String]
+    let emergingSignals: [String]
+    let changesSinceYesterday: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case date, priorities, ignored
+        case emergingSignals = "emerging_signals"
+        case changesSinceYesterday = "changes_since_yesterday"
+    }
+}
+
+// MARK: - Decision
+
+struct SyncDecision: Codable, Identifiable {
+    let id: String
+    let decision: String
+    let reason: String
+    let project: String
+    let assumptions: [String]
+    let contextTags: [String]
+    let createdAt: String
+    let outcome: String
+    let impactScore: Double
+
+    enum CodingKeys: String, CodingKey {
+        case id, decision, reason, project, assumptions, outcome
+        case contextTags = "context_tags"
+        case createdAt = "created_at"
+        case impactScore = "impact_score"
+    }
+}
+
+// MARK: - Insight
+
+struct SyncInsight: Codable, Identifiable {
+    let id: String
+    let title: String
+    let summary: String
+    let whyItMatters: String
+    let architecturalImplication: String
+    let nextAction: String
+    let confidence: Double
+    let tags: [String]
+    let relatedProject: String
+    let createdAt: String
+
+    enum CodingKeys: String, CodingKey {
+        case id, title, summary, confidence, tags
+        case whyItMatters = "why_it_matters"
+        case architecturalImplication = "architectural_implication"
+        case nextAction = "next_action"
+        case relatedProject = "related_project"
+        case createdAt = "created_at"
+    }
+}
+
+// MARK: - Signal
+
+struct SyncSignal: Codable, Identifiable {
+    let id: String
+    let topic: String
+    let frequency: Int
+    let strength: Double
+    let status: String  // emerging, confirmed, fading, archived
+    let firstSeen: String
+    let lastSeen: String
+    let sourceTitles: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case id, topic, frequency, strength, status
+        case firstSeen = "first_seen"
+        case lastSeen = "last_seen"
+        case sourceTitles = "source_titles"
+    }
+}
+
+// MARK: - Working Memory
+
+struct SyncWorkingMemory: Codable {
+    let date: String
+    let todaysPriorities: [String]
+    let currentlyExploring: [String]
+    let temporaryNotes: [String]
+
+    enum CodingKeys: String, CodingKey {
+        case date
+        case todaysPriorities = "todays_priorities"
+        case currentlyExploring = "currently_exploring"
+        case temporaryNotes = "temporary_notes"
+    }
+}

CortexOSApp/Shared/Services/APIService.swift

@@ -203,6 +203,26 @@ final class APIService: ObservableObject {
     func evaluateWhy(_ body: WhyEvaluateRequest) async throws -> DecisionResult {
         try await request("POST", path: "/why/evaluate", body: body)
     }
+
+    // MARK: - Sync
+
+    func fetchSnapshot() async throws -> SyncSnapshot {
+        try await request("GET", path: "/sync/snapshot")
+    }
+
+    // MARK: - Context (mutations)
+
+    func recordDecision(_ body: DecisionCreateRequest) async throws -> SyncDecision {
+        try await request("POST", path: "/context/decision", body: body)
+    }
+
+    func recordOutcome(_ body: OutcomeCreateRequest) async throws -> SyncDecision {
+        try await request("POST", path: "/context/outcome", body: body)
+    }
+
+    func storeInsight(_ body: InsightCreateRequest) async throws -> SyncInsight {
+        try await request("POST", path: "/context/insight", body: body)
+    }
 }
 
 // MARK: - Helpers

cortex_core/api/routes/sync.py

@@ -0,0 +1,27 @@
+"""
+Sync API route
+--------------
+GET /sync/snapshot — single-call pull of everything a Swift client needs.
+
+One endpoint. One model. Backend is source of truth.
+Clients pull this on launch and on-demand refresh.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from cortex_core.api.server import get_engine
+
+router = APIRouter(prefix="/sync", tags=["sync"])
+
+
+@router.get("/snapshot")
+async def get_snapshot() -> dict:
+    """Return a single sync snapshot for Apple clients.
+
+    Bundles profile, active project, priorities, recent decisions,
+    insights, signals, and working memory into one response.
+    """
+    engine = get_engine()
+    return engine.build_sync_snapshot()

cortex_core/api/server.py

@@ -56,11 +56,12 @@ def create_app() -> FastAPI:
     )
 
     # Register routers
-    from cortex_core.api.routes import context, digest, focus, health, knowledge, pipeline, posts, profile, why
+    from cortex_core.api.routes import context, digest, focus, health, knowledge, pipeline, posts, profile, sync, why
 
     app.include_router(health.router)
     app.include_router(focus.router)  # primary feature
     app.include_router(why.router)  # why engine — per-item intelligence
+    app.include_router(sync.router)  # single-call sync for Apple clients
     app.include_router(context.router)  # agent context API
     app.include_router(profile.router)
     app.include_router(knowledge.router)

cortex_core/engine.py

@@ -484,6 +484,46 @@ def get_full_context(self) -> dict:
         """Return complete memory state for agent consumption."""
         return self.memory.full_context()
 
+    # ── Sync ────────────────────────────────────────────────────
+
+    def build_sync_snapshot(self) -> dict:
+        """Single-call snapshot of everything Apple clients need.
+
+        Bundles profile, active project, priorities, decisions,
+        insights, signals, and working memory into one dict.
+        Backend is source of truth — clients pull this on launch.
+        """
+        from datetime import UTC, datetime
+
+        profile = self.memory.profile
+
+        # Active project context (first project, if any)
+        active_project: dict | None = None
+        if profile.current_projects:
+            pm = self.memory.get_project(profile.current_projects[0])
+            active_project = pm.to_dict()
+
+        # Priority brief (may not exist yet)
+        priorities = self.decision_engine.get_previous_brief()
+
+        return {
+            "profile": {
+                "name": profile.name,
+                "role": profile.role,
+                "goals": profile.goals,
+                "interests": profile.interests,
+                "current_projects": profile.current_projects,
+                "ignored_topics": profile.ignored_topics,
+            },
+            "active_project": active_project,
+            "priorities": priorities,
+            "recent_decisions": self.get_recent_decisions(10),
+            "insights": self.get_insights(limit=10),
+            "signals": self.get_signals(),
+            "working_memory": self.memory.working.to_dict(),
+            "synced_at": datetime.now(UTC).isoformat(),
+        }
+
     # ── Why Engine ──────────────────────────────────────────────
 
     def evaluate_why(self, item_data: dict) -> dict:

tests/test_api.py

@@ -154,3 +154,55 @@ def test_run_pipeline(self, client, tmp_data_dir, sample_digest_text):
         assert resp.status_code == 200
         data = resp.json()
         assert "success" in data
+
+
+# ── Sync ────────────────────────────────────────────────────────
+
+
+class TestSyncEndpoints:
+    def test_snapshot_returns_200(self, client):
+        resp = client.get("/sync/snapshot")
+        assert resp.status_code == 200
+
+    def test_snapshot_has_required_keys(self, client):
+        data = client.get("/sync/snapshot").json()
+        for key in ("profile", "active_project", "priorities",
+                     "recent_decisions", "insights", "signals",
+                     "working_memory", "synced_at"):
+            assert key in data, f"missing key: {key}"
+
+    def test_snapshot_profile_shape(self, client):
+        profile = client.get("/sync/snapshot").json()["profile"]
+        assert isinstance(profile["goals"], list)
+        assert isinstance(profile["interests"], list)
+        assert isinstance(profile["current_projects"], list)
+        assert "name" in profile
+        assert "role" in profile
+
+    def test_snapshot_synced_at_is_iso(self, client):
+        data = client.get("/sync/snapshot").json()
+        # Should be a valid ISO timestamp
+        assert "T" in data["synced_at"]
+
+    def test_snapshot_recent_decisions_is_list(self, client):
+        data = client.get("/sync/snapshot").json()
+        assert isinstance(data["recent_decisions"], list)
+
+    def test_snapshot_signals_is_list(self, client):
+        data = client.get("/sync/snapshot").json()
+        assert isinstance(data["signals"], list)
+
+    def test_snapshot_working_memory_shape(self, client):
+        wm = client.get("/sync/snapshot").json()["working_memory"]
+        assert "date" in wm
+        assert isinstance(wm["todays_priorities"], list)
+
+    def test_snapshot_after_decision_includes_it(self, client):
+        client.post("/context/decision", json={
+            "decision": "Use rule-based scoring for v1",
+            "reason": "Simplicity over accuracy at this stage",
+            "project": "CortexOS",
+        })
+        decisions = client.get("/sync/snapshot").json()["recent_decisions"]
+        texts = [d["decision"] for d in decisions]
+        assert "Use rule-based scoring for v1" in texts