examples/ios/DolphinCoreMLTestApp/CREATE_STATE_INTEGRATION.md

Create State-Inspired Local Continuity Blueprint

Evidence snapshot: 2026-07-20

Scope and parity boundary

This document translates capabilities visible in Create State's public repositories and public product documentation into a private, on-device design for Dolphin. It is an engineering blueprint, not a claim that Dolphin reproduces Create State's hosted service.

The public clients are mostly adapters to a private MCP service. The service implementation, data model, retrieval stack, prompts, schedulers, and policy engines are not public. Dolphin must therefore implement independently described local behavior, label its algorithms accurately, and avoid claiming compatibility or parity with unavailable Create State internals.

Status labels in this document mean:

• Existing: present in Dolphin before this integration.
• This implementation: in scope for the current local continuity change set. This is not considered complete until the acceptance criteria below pass.
• Deferred: intentionally outside this change set.

The code-level integration is present. Release acceptance remains deliberately separate: host tests and a non-launching iOS build are verified below, while physical-device model evidence and the remaining UI/privacy checks are open.

Public evidence baseline

At the snapshot date, the public Create-State GitHub organization exposed three repositories. The links below are pinned to the exact main revisions inspected.

Public artifact	Immutable revision	Relevant evidence
Python client and CLI	0b2ef05effb43b8bd46c20f6371f2d715a71d136	client.py, cli.py, README.md, CHANGELOG.md, LICENSE
VS Code extension	5c522b84a9079baa48991eff2d2b1e7261e4aab5	mcpClient.ts, chatParticipant.ts, commands.ts, auth.ts, security.test.ts
Cursor plugin	06c6c4ca471e402a7d61fdd1b85ed75e9fff78a9	mcp.json, session-workflow.mdc, knowledge-capture.mdc, commit-workflow.mdc, knowledge-capture/SKILL.md, session-restore/SKILL.md

The following product pages are useful but mutable and are therefore not immutable implementation evidence: Features, API, Teams, Privacy, Security policy, and What's new.

The public Python allowlist exposes these 18 MCP tool contract names:

analyze_code
analyze_code_with_intelligence
captureCode
captureConversationContext
createSessionHandoff
createWorldModel
detect_patterns
getProactiveInsights
getProjectWorldModel
getShowerThinkingInsights
listHandoffPackages
listUserWorldModels
llmChat
queryWorldModel
restoreFromHandoff
searchProjectKnowledge
startProjectMonitoring
synthesizeProjectContext

The website describes more than 40 tools, but no complete public server-side tool registry was available. The 18 names above are a public client contract, not proof of each server algorithm.

Public capability inventory

Knowledge and continuity

• A world model acts as a durable project or domain container.
• Explicit captures record code, conversation context, decisions, facts, goals, and insights as evolving knowledge.
• Public documentation describes capture history/versioning and synthesis after accumulated captures.
• Query surfaces distinguish graph-style querying, project knowledge search, and model-grounded chat.
• A session handoff packages current focus, recent context, knowledge, hypotheses or pending insights, and work in progress; handoffs can be listed and restored.
• Proactive insights and “shower thinking” expose prioritized follow-up ideas; project monitoring accepts project goals.

Analysis and imports

• Public contracts include code analysis, intelligence-assisted analysis, and pattern detection.
• Product pages describe pattern, anti-pattern, algorithm, and idiom recognition. The claimed trained corpus and private inference engine are not reproducible from public client code.
• GitHub import is described as an asynchronous pipeline with repository/branch selection and phases such as pending, cloning, extracting, populating, completed, and failed.
• Product pages describe image normalization, metadata removal, moderation, vision tagging/description, OCR, and thumbnails.

Clients, teams, and operations

• Public clients use MCP-flavored JSON-RPC 2.0 over HTTP with a client-type marker and OAuth or bearer authorization.
• The VS Code extension provides device-flow authentication, secret storage, explicit commands, a chat participant, a sidebar, and a deterministic regex intent router.
• The Cursor plugin supplies setup checks, MCP configuration, hooks, workflow rules, and reusable capture/restore skills.
• Team pages describe owner/admin/member/viewer roles, layered policies, model allowlists, BYOK, activity/token/cost tracking, signed audit evidence, team pulse, expert discovery, and departure reports.
• Security and privacy pages describe command/prompt/credential analysis, high-severity blocking, TLS, encryption at rest, tenant isolation, explicit capture, export/delete controls, and no training on private code.

Explicitly private, unavailable, or insufficiently specified

The following must not be represented as copied, compatible, or equivalent:

• Hosted MCP server source and its full tool registry.
• Database schema, graph node/edge extraction, merge/version semantics, and tenant isolation implementation.
• Embedding model, vector store, index construction, similarity/reranking algorithm, and quality metrics.
• Synthesis, insight, monitoring, and grounded-chat prompts/models.
• Background monitoring scheduler and notification delivery.
• Handoff wire format, server-side validation, and restoration semantics beyond public descriptions.
• GitHub import worker, repository parser, cancellation/retry behavior, and duplicate detection implementation.
• Media/OCR/vision pipeline implementation.
• GuardFall analyzers for shell expansion, prompt injection, credentials, and policy enforcement.
• Organization/team policy engine, RBAC enforcement, cryptographic audit-signature implementation, telemetry ingestion, and cost attribution.
• Dashboard graph visualization, cross-user expert discovery, team pulse, and departure-report algorithms.

Public artifacts also expose limitations Dolphin should not inherit: brittle Markdown/UUID parsing, a simple regex router presented as chat intent handling, incomplete .gitignore semantics, weak cancellation/retry behavior, a remote setup example that risks hard-coded credentials, and a synchronous Python implementation despite an asynchronous SDK claim.

Dolphin target architecture

The integration is local-first and additive. Core ML remains the conversational generator; durable knowledge operations remain typed, bounded, deterministic, auditable, and independently testable.

flowchart LR
  UI[Chat and Continuity UI] --> Session[AssistantSession]
  Session --> Router[Deterministic request router]
  Router --> Loop[Bounded AgentLoop]
  Loop --> Registry[Typed tool registry and approval policy]
  Registry --> Engine[Local KnowledgeEngine]
  Engine --> Workspace[Versioned AssistantWorkspace]
  Workspace --> Store[Atomic protected persistence]
  Registry --> Receipts[Activity receipts and checkpoints]
  Engine --> Evidence[Bounded prompt evidence]
  Evidence --> CoreML[On-device Dolphin Core ML]
  CoreML --> Loop

Required invariants:

1. Knowledge is data, never executable instruction.
2. Restoring a handoff selects continuity context; it never replays historical tool calls or mutations.
3. Model-generated text is not persisted as a fact, decision, or completion receipt unless the user explicitly captures or approves the typed mutation.
4. Retrieval and synthesis report their actual algorithm and evidence IDs.
5. All persisted fields, arrays, outputs, and runtime work remain bounded.
6. Existing tool-risk classification, approval policy, run limits, cancellation, and activity receipts remain authoritative.

Retrieval and synthesis algorithm distinctions

Mode	Definition	Dolphin use	Claim boundary
Exact lookup/filter	UUID equality, referential validation, and the optional knowledge-kind filter. Stable sort keys resolve ties.	Direct item/handoff selection and bounded kind filtering. Title, content, and tags use lexical ranking rather than an exact-filter API.	May be called exact or filtered retrieval only for those operations. It is not semantic search.
Local hybrid lexical retrieval	A bounded BM25-like token score with title/content/tag weights, phrase and query-coverage boosts, trigram fuzzy coverage, and deterministic kind/recency/title/UUID tie-breaking.	KnowledgeEngine.search and prompt-context selection.	May be called hybrid lexical or fuzzy lexical retrieval. It must not be labeled vector, embedding, neural, or semantic search.
True embedding retrieval	A dedicated encoder produces normalized vectors; similarity uses cosine/dot product or a validated ANN index, with persisted model/index versions and retrieval evaluation.	Deferred until an on-device embedding model, index lifecycle, memory budget, privacy review, and relevance benchmark are supplied.	Dolphin generator logits or hidden states are not an embedding service unless an exported embedding head is validated for this purpose.
Deterministic synthesis	Typed templates select decisions, preferences, goals, open tasks, recent context, and evidence IDs under hard limits.	Project digest, handoff summary, and proactive continuity/quality suggestions in this implementation.	This is rule-based synthesis, not model reasoning.
Core ML response generation	The local language model receives bounded, labeled, untrusted evidence and generates a response.	Conversational explanation after retrieval.	Generated prose is interpretation, not proof that a tool ran or that a fact is true.

Capability-to-Dolphin mapping

Create State-inspired capability	Status	Dolphin implementation or boundary
Bounded autonomous tool loop	Existing	AgentLoop enforces tool-step, output, and time limits with explicit completion/cancellation behavior.
Intent/tool routing	Existing + expanded	AgentRequestRouter emits an inspectable conversation, deterministic, or model-assisted-read contract. Explicit sequences require call-correlated receipts and finish from verified renderers without a follow-up model turn; heuristic routing exposes reads only.
Risk and approval controls	Existing	Read-only vs local-write risk, approval gates, capability gates, receipts, and run checkpoints remain in force.
Private workspace persistence	Existing	Atomic protected JSON persistence and workspace migration provide the storage base.
Legacy memories and tasks	Existing	Memory search/save and task list/add/complete remain supported and must survive migration.
Calendar read context	Existing	EventKit read adapter remains capability-gated and separate from knowledge storage.
Siri/App Intent entry	Existing + this implementation	Ask, Continue, and Capture Context only place sanitized inert text in the composer. They do not bypass approval, run tools, restore a handoff, or save knowledge in the extension.
Typed knowledge records	This implementation	Local KnowledgeItem values cover fact, preference, decision, goal, code, context, and insight with source, tags, relationships, timestamps, and a bounded revision field. The current UI creates and deletes records; it does not claim edit history, lineage, or automatic revision increments.
Input neutralization and bounds	This implementation	Central sanitization strips controls, neutralizes agent/tool delimiters, deduplicates IDs/tags, and enforces corpus/field/result limits.
Knowledge capture and deletion	This implementation	Continuity UI supports explicit structured capture/delete. Any agent-facing capture is a typed local-write mutation and requires the normal approval path.
Exact and hybrid lexical search	This implementation	Deterministic filtered lookup plus bounded BM25-like/phrase/coverage/trigram ranking; no embedding claim. Legacy memories may be presented beside typed knowledge without silently rewriting provenance.
Project-context synthesis	This implementation	Deterministic digest from typed knowledge, open tasks, current handoff, bounded priorities/questions, and evidence IDs. No cloud or hidden model call.
Prompt grounding	This implementation	Selected knowledge becomes bounded MemoryItem-compatible prompt evidence labeled by kind; stored text remains untrusted context.
Session handoff creation	This implementation	Typed package contains focus, summary, next steps, knowledge IDs, task IDs, and timestamps under hard limits.
Handoff list/restore/delete	This implementation	Continuity UI exposes saved handoffs and an active marker. Restore validates a UUID and selects context only; delete is explicit.
Proactive continuity insights	This implementation	Deterministic rules flag conflicting knowledge, unsupported open tasks, stale handoffs, missing relationships, and missing tags with evidence IDs and priorities. No background autonomy.
Local code analysis	This implementation	Read-only bounded heuristics report TODO/FIXME, forced try, force unwrap, forced cast, long lines, approximate nesting, and repeated lines. Source is never executed or uploaded.
Continuity UI	This implementation	Replace the Memory surface with Knowledge, Handoffs, and Tasks views while retaining legacy memories and task operations.
Persisted knowledge/digests/handoffs	This implementation	Schema-v5 workspace fields, safe decode defaults for prior schemas, active-handoff validation, bounded collections, and atomic protected persistence are wired.
Agent tool exposure for knowledge operations	This implementation + expanded	Fourteen continuity tools are wired through registry, router, risk classes, bounds, strict grounded renderers, approvals, and receipts. The new tranche adds knowledge_get, project_review, task_search, handoff_get, task_reopen, and handoff_deactivate to the existing search/capture/context/handoff/insight/code tools. Destructive knowledge and handoff deletion remain explicit UI-only actions.
Multiple independent world models	Deferred	Current app has one local workspace. Add model selection and isolated stores only with a migration/export design.
Automatic synthesis after capture threshold	This implementation	A bounded deterministic digest is stored whenever the typed knowledge count reaches a multiple of five, including mirrored legacy-memory captures. This is derived data within the approved/direct capture transaction, not a background model action.
True vector/embedding search	Deferred	Requires a dedicated on-device embedding pipeline and measured retrieval quality.
Background monitoring and notifications	Deferred	No scheduler or unsupervised background agent loop.
Hosted MCP/OAuth/Bearer client	Deferred	No Create State network call, account linkage, or remote dependency.
GitHub/repository import	Deferred	Requires scoped credentials, branch/ref provenance, parser limits, cancellation, licensing review, and an import UI.
Chat/Claude/other assistant imports	Deferred	Requires explicit export ingestion, provenance, deduplication, redaction, and deletion controls.
Image/OCR/vision ingestion	Deferred	Requires on-device or explicitly consented processing, metadata stripping, moderation, and storage limits.
Team graph, sync, RBAC, BYOK, and governance	Deferred	Single-user local app has no claim to tenant isolation, team policy, or collaborative audit semantics.
Usage/cost telemetry and signed audit evidence	Deferred	Local receipts are not equivalent to server-side HMAC nonrepudiation or organization telemetry.
GuardFall-equivalent security engine	Deferred	Current sanitization and approval rules are narrower defenses, not parity with the claimed private analyzers.
Dashboard graph visualization and expert discovery	Deferred	Relationships remain typed local IDs; no inferred organization graph or cross-user ranking.

Security adaptations for an on-device assistant

• No remote dependency: this implementation must not send knowledge, code, prompts, model output, or diagnostics to Create State or another service.
• Protected storage: retain atomic writes and completeFileProtectionUnlessOpen; migrate existing data without temporarily writing an unprotected copy.
• Credential hygiene: no API key is required. Any future integration must use Keychain/AuthenticationServices, never source, UserDefaults, model prompts, or checked-in configuration.
• Explicit capture: durable capture/delete/restore operations are visible user actions. Agent-originated local writes use the existing approval policy.
• Typed boundaries: accept Codable payloads and validated UUIDs, not UUID extraction from Markdown or model prose. Reject unknown fields and invalid enum values.
• Prompt-injection isolation: neutralize system/assistant/tool delimiters and control characters at capture and prompt boundaries. Wrap retrieved text as quoted untrusted evidence; never concatenate it into system instructions.
• No action replay: handoff restore only marks a package active and supplies context. Historical calls, approvals, and completion claims cannot be replayed.
• Provenance and revision: retain source, timestamps, revision, kind, tags, relationships, and evidence IDs. Do not merge contradictory records silently.
• Bounds and denial-of-service controls: cap corpus size, code input, content, tags, relationships, search results, prompt evidence, insight count, handoff contents, and rendered output.
• No code execution: local analysis examines a bounded string only. It does not invoke a shell, compiler, package manager, network client, or dynamic evaluator.
• Truthful receipts: distinguish tool execution evidence from model interpretation. A generated acknowledgement cannot serve as a mutation receipt.
• Explicit deletion scope: deleting knowledge, a memory mirror, a task, or a handoff confirms and discloses any cascading removal of derived handoffs/digests. Original chat and run Activity remain until the separately labeled Clear Chat & Run Activity action is used; that action also scrubs copied recent-chat excerpts from retained handoffs.
• Future export/delete: before network sync or imports, add complete local export and verified delete behavior, including derived digests and handoffs.
• License boundary: the public clients are MIT-licensed, but direct code reuse must retain the required notice. Prefer independent Swift implementation of documented behavior.

Acceptance criteria

Data and migration

• Existing installations load without loss of conversations, settings, legacy memories, tasks, activity receipts, or checkpoints.
• The workspace schema persists typed knowledge, digests, handoffs, and active-handoff identity atomically under file protection.
• Decode defaults are safe for prior schemas; corrupt or dangling relationship IDs are rejected or surfaced without crashing.
• Delete behavior defines what happens to related IDs, digest evidence, and the active handoff; no invisible orphaning is introduced.
• Round-trip tests cover every knowledge kind/source/priority, revisions, relationships, handoffs, digests, active selection, and legacy migration.

Retrieval and algorithms

• Repeated searches over identical data return identical ordering, including score ties.
• Tests cover title/content/tag weighting, phrase boost, token coverage, trigram tolerance, kind filters, result limits, empty queries, diacritics, and stable tie-breaking.
• User-facing and tool output identifies the retrieval mode as exact or hybrid lexical and never says semantic, embedding, vector, or neural search.
• True embedding search stays disabled until a dedicated encoder/index is versioned and evaluated against a relevance fixture.
• Deterministic digests and insights contain only bounded data traceable to evidence IDs; generated prose is never silently stored as durable truth.

Agent and tool safety

• Every new agent-facing operation has a canonical definition, strict schema, normalized arguments, unknown-field rejection, risk classification, output cap, and deterministic receipt.
• Agent-originated capture and handoff create/restore use exact local-write approval. Direct UI capture/delete/create/restore is itself the visible user action. Automatic digest creation is derived inside capture. Read-only search, context, insight, and analysis cannot mutate workspace state.
• Router tests cover command collisions and ensure ordinary greetings do not trigger capture, restore, deletion, analysis, or task mutation.
• Retrieved/captured strings containing <system>, <assistant>, <tool_call>, <tool_response>, control characters, or misleading action claims cannot become control tokens or execution evidence.
• Cancellation and run-limit tests show that partially prepared mutations are not persisted.
• Restoring a handoff never invokes a historical tool, adopts an old approval, marks a task complete, or asserts that work was executed.

UI and accessibility

• Knowledge, Handoffs, and Tasks remain usable with empty, populated, long-content, error, and migrated states.
• Manual capture validates kind/title/content/tags and clearly distinguishes a saved record from an assistant response.
• Handoff active/restored state, delete actions, evidence links, insight priority, and legacy-memory provenance are visible.
• Dynamic Type, VoiceOver labels, focus order, contrast, keyboard avoidance, and destructive-action confirmation are verified on supported iPhone sizes.

Analysis, privacy, and release evidence

• Code analysis is deterministic, bounded to the documented character limit, labeled heuristic, never executes input, and never performs a network request.
• Network inspection or an injected transport spy verifies zero knowledge/code egress in this change set.
• Host tests pass, the iOS target builds without launching, and a migration fixture is exercised.
• Physical-device validation separately proves model-backed chat plus capture → search → synthesize → handoff → restore continuity. Compile success or fallback text alone is not runtime proof.
• Release notes use “Create State-inspired local continuity” and enumerate the deferred items; they do not claim Create State compatibility, private implementation access, complete 40+ tool parity, semantic search, team security parity, or hosted-service equivalence.

Verification snapshot

Evidence	Current result
Host protocol/engine suite	Passed: 94 tests completed with zero failures on 2026-07-21. Coverage includes deterministic plans and receipts, hidden-reasoning rejection, strict correlated read rendering, router/registry parity, no-model tool execution, task ranking, and local-write lifecycle tests.
iOS compile and metadata extraction	Passed: xcodebuild ... build-for-testing for generic iOS Simulator completed with TEST BUILD SUCCEEDED; App Intents metadata was generated for Ask, Continue, and Capture Context. The app was not launched.
Retrieval terminology	Passed for the agent surface: tool payload and deterministic chat rendering identify local hybrid lexical retrieval. No embedding or semantic-search claim is made.
Private-service boundary	Passed by construction: the production registry exposes no network tool and the continuity engine has no transport dependency. A transport-spy or packet-capture artifact remains open.
UI and accessibility walkthrough	Partially implemented, runtime verification open: field limits/counters, destructive cascade confirmations, legacy-memory search, and handoff deactivation compile. Empty/populated/error states, Dynamic Type, VoiceOver, focus, keyboard avoidance, and evidence-link presentation still require simulator/device validation and any resulting fixes.
Physical-device model continuity	Open: a real Core ML run must separately prove capture → search → synthesize → handoff → restore. Compile/test success is not model-backed runtime evidence.

Follow-on order

1. Close the remaining deterministic fixture matrix and perform simulator UI/accessibility checks, including evidence presentation.
2. Capture physical-device, model-backed continuity evidence before expanding the tool surface.
3. Add complete export/delete and richer provenance UX before any importer or sync design.
4. Add an injected transport assertion or network-inspection artifact for release privacy evidence.
5. Evaluate a dedicated on-device embedding model against a fixed retrieval benchmark before changing search terminology.
6. Treat network sync, repository/media imports, monitoring, and team governance as separate threat-modeled projects with explicit user consent.