Upgrade to 2.0.0

Move from 1.6, 1.7 or 1.8 to 2.0.0

FabrCore 2.0 brings the current agent runtime and integrations together. This is a breaking package and configuration release. Rebuild consuming libraries and applications, preserve existing database mappings, and migrate ACL before cutover.

The baseline is .NET 10, Orleans 10.3.1 and Microsoft Agent Framework 1.20.0. Apply the intervening changes below when skipping releases; deploying every intermediate version is not required.

1. Replace retired packages

No forwarding packages are published. Existing FabrCore.Services.* namespaces remain where applicable; do not blindly rename namespaces to match assembly names. The old lightweight FabrCore.Sdk.Memory API is removed and requires an explicit migration to scoped Memory.

dotnet add package FabrCore.Host --version 2.0.0
# Agent libraries and HTTP API consumers:
dotnet add package FabrCore.Sdk --version 2.0.0

Keep all directly referenced FabrCore packages on 2.0.0. The supported set is Core, Connections, Sdk, Host, Surface, Client.Orleans, Client.WebSocket, Host.AzureStorage, Host.Testing, Services.Microsoft365Copilot, Services.Connections and Services.RemoteAgents. Remove retired NuGet/project references and manual Memory/GraphRAG service/admin registrations. AddFabrCoreServer() now integrates those services.

2. Choose the intended runtime mode

Configure ConnectionStrings:FabrCore to retain enforced ACL and enable SQL features. Without the feature connection, standalone trusts cross-principal messaging and defaults to in-memory state lost on restart. See database modes for prerequisites, model aliases, split connections and startup behavior.

3. Export and import ACL data

1. Back up databases and retain old binaries/configuration. Export ACL while the old host is running.
2. Configure the new SQL host, models and FabrCore:AdminAuthentication:ApiKey. Preserve old seeds as migration input, then remove seeds/rules from startup configuration.
3. Initialize the new schema and import into a target containing only built-in ACL entities.
4. Validate identities, memberships, grants, allow/deny behavior and readiness before routing traffic.

The release's scripts/Migrate-Acl.ps1 uses FABRCORE_ADMIN_API_KEY. Supply the appropriate old/new host credential through the environment.

./scripts/Migrate-Acl.ps1 -Mode Export -HostUrl https://old-host -Path acl-export.json
./scripts/Migrate-Acl.ps1 -Mode Import -HostUrl https://new-host -Path acl-export.json

Import preserves IDs, validates references and commits transactionally. It refuses to overwrite user-defined target ACL data. Old FabrCore:Acl:Seed JSON is accepted as migration input, not normal startup configuration. Freeze ACL writes during final export/cutover. This utility does not migrate conversations or application/knowledge databases.

4. Restore-test existing Orleans state

Preserve cluster/service IDs, storage names and connection mappings. Orleans now validates persisted JSON $type metadata. Explicitly register application-specific persisted types and nested types with TypeManifestOptions.AddAllowedType; keep AllowAllTypes disabled. The JsonElement fix cannot recover already-lost data.

Memory streams remain the default. Optional SQL streams use the pinned Orleans 10.3.1-alpha.1 provider; FabrCore 2.0 does not change that upstream preview designation. Set the same stream mode on every silo, drain publishers and restart the cluster when switching. Memory queues are not migrated. Validate direct stream clients and schema provisioning separately.

5. Apply earlier boundaries when needed

• 1.6: use FabrCore:RemoteAdministration:Enabled; Cloud Server remains optional. 1.6.0 aliases 1.5.0.
• 1.7: migrate raw WebSockets to v2 tickets/hello, move swarm.squads to top-level squads, replace Swarm with orchestrator/task squads, and update retired compaction/checkpoint APIs. Harness execution uses _plan-mode=false and the result's RunAsync.
• 1.7.1: remote model-configuration endpoints require the admin bearer credential; in-process resolution uses the local store.
• 1.8: A2A hosting is built into Host but opt-in. Removed SDK A2A adapters are replaced by background delegation or actual A2A protocol integration. Custom resolvers use ResolvePrincipalHandleAsync. 1.8.1 has no additional runtime migration.

6. Verify before cutover

Build all consumers and test startup, model resolution, chat/tool calls and affected transports. On a restored database copy, verify conversations, custom state, typed storage, ACL isolation, Memory scopes/recall and GraphRAG ingestion/search across restart. A successful build does not prove mixed-version Orleans compatibility. Retain a consistent pre-upgrade backup for rollback; do not point old binaries at migrated schemas.

Read the 2.0 compaction guide for revised budgets and safe history writes. SQL A2A snapshots persist, but interrupted execution is not replayed and SSE history is not durable.

Cloud administration is part of the 2.0 release

Adopt capability discovery and the administration API for conditional ACL/blueprint writes, typed summary pages, agent management, isolated diagnostics, monitoring and evidence exports. These features require no later FabrCore version or cloud WebSocket migration. Preserve older-host fallbacks and HTTP conditions/leases through the broker.

Reserve _admin and _debug outside ordinary message channels. Provision durable storage for operator sessions and operation recovery. SQL monitoring is optional; apply its additive migration before enabling it in manual-schema mode. Rehearse lifecycle, actor isolation, incomplete-operation and cluster coverage behavior before release cutover.