swift-ddd-kit  0.x → 1.0

🤖 AI Migration Manifest（機器可讀）

若你是 AI agent,正在把一個依賴 swift-ddd-kit 的專案從 0.x 升到 1.0 — 直接消化下方 JSON。每條規則含 kind(變更類型)、mechanical (能否純文字取代)、before/after、action(對下游要做什麼)。 套用順序:先做 mechanical:true 的 rename,再處理 signature-change / removed。scope 標示要掃描的程式碼位置。

{
  "schema": "swift-ddd-kit-migration/v1",
  "package": "swift-ddd-kit",
  "from": "0.x",
  "to": "1.0",
  "domainLayerImpact": "none",
  "applyOrder": ["rename", "signature-change", "removed", "new"],
  "rules": [
    {
      "id": "R1",
      "kind": "rename",
      "mechanical": true,
      "scope": "any type reference to the storage protocol",
      "before": "EventStorageCoordinator",
      "after": "EventStore",
      "note": "Only the PROTOCOL was renamed. Concrete classes InMemoryStorageCoordinator and KurrentStorageCoordinator keep their names (see R5/R6).",
      "action": "Replace every reference to the protocol name `EventStorageCoordinator` with `EventStore` — in `: EventStorageCoordinator` conformances, `any EventStorageCoordinator` existentials, and generic constraints."
    },
    {
      "id": "R2",
      "kind": "rename",
      "mechanical": true,
      "scope": "types conforming to EventSourcingRepository or EventSourcingProjector",
      "before": "typealias StorageCoordinator = SomeStore",
      "after": "typealias Store = SomeStore",
      "action": "Rename the `StorageCoordinator` associated-type witness to `Store` in every Repository and Projector conformer."
    },
    {
      "id": "R3",
      "kind": "rename",
      "mechanical": true,
      "scope": "types conforming to EventSourcingRepository or EventSourcingProjector",
      "before": "var coordinator: SomeStore  /  self.coordinator  /  x.coordinator",
      "after": "var store: SomeStore  /  self.store  /  x.store",
      "action": "Rename the `coordinator` stored property to `store`, and every read of `.coordinator` on a repository/projector to `.store`. Also rename the matching `init(coordinator:)` label to `init(store:)`."
    },
    {
      "id": "S1",
      "kind": "signature-change",
      "mechanical": false,
      "scope": "every use of KurrentStorageCoordinator as a type or constructor",
      "before": "KurrentStorageCoordinator",
      "after": "KurrentStorageCoordinator",
      "action": "Add a second generic argument: the metadata schema type. Use `CustomMetadata` for the bundled default, or your own `EventMetadata`-conforming struct. Applies to `typealias Store = …`, property types, and `KurrentStorageCoordinator<…>(client:eventMapper:)` constructor calls."
    },
    {
      "id": "S2",
      "kind": "signature-change",
      "mechanical": false,
      "scope": "every use of InMemoryStorageCoordinator as a type or constructor",
      "before": "InMemoryStorageCoordinator  /  InMemoryStorageCoordinator()",
      "after": "InMemoryStorageCoordinator  /  InMemoryStorageCoordinator()",
      "action": "Add the metadata schema as a generic argument everywhere InMemoryStorageCoordinator is named — typealias, property type, and constructor."
    },
    {
      "id": "S3",
      "kind": "signature-change",
      "mechanical": false,
      "scope": "custom hand-written types conforming to EventStore (the renamed protocol)",
      "before": "func append(events:, byId:, version:, external: [String:String]?) async throws -> UInt64?",
      "after": "associatedtype Metadata: EventMetadata\n    func append(events:, byId:, version:, metadata: Metadata?) async throws -> UInt64?",
      "action": "If the project defines its own EventStore implementation: add `associatedtype Metadata: EventMetadata` (or a `typealias`), and change `append`'s last parameter from `external: [String:String]?` to `metadata: Metadata?`. `fetchEvents` and `purge` signatures are unchanged."
    },
    {
      "id": "S4",
      "kind": "signature-change",
      "mechanical": false,
      "scope": "every call site of repository.save(aggregateRoot:external:)",
      "before": "try await repository.save(aggregateRoot: x, external: [\"userId\": uid])",
      "after": "try await EventMetadataContext.withValue(CustomMetadata(operatorId: uid)) {\n    try await repository.save(aggregateRoot: x)\n}",
      "action": "Remove the `external:` argument from save. If metadata was being passed, wrap the call in `EventMetadataContext.withValue(metadata) { … }`. If `external` was nil/unused, just delete the argument.",
      "note": "M must equal the Store.Metadata of that repository's store."
    },
    {
      "id": "S5",
      "kind": "signature-change",
      "mechanical": false,
      "scope": "every call site of repository.delete(byId:external:)",
      "before": "try await repository.delete(byId: id, external: …)",
      "after": "try await repository.delete(byId: id)   // optionally wrapped in EventMetadataContext.withValue",
      "action": "Remove the `external:` argument from delete. delete internally calls save, so wrap in EventMetadataContext.withValue if a delete-time metadata payload is needed."
    },
    {
      "id": "D1",
      "kind": "removed",
      "mechanical": false,
      "scope": "call sites of the userId convenience overloads",
      "before": "try await repository.save(aggregateRoot: x, userId: uid)",
      "after": "try await EventMetadataContext.withValue(CustomMetadata(operatorId: uid)) {\n    try await repository.save(aggregateRoot: x)\n}",
      "action": "The `save(aggregateRoot:userId:)` and `delete(byId:userId:)` convenience overloads (KurrentSupport) are DELETED. Replace with an explicit EventMetadataContext.withValue scope."
    },
    {
      "id": "D2",
      "kind": "removed",
      "mechanical": false,
      "scope": "call sites of repository.delete(byId:userId:)",
      "before": "try await repository.delete(byId: id, userId: uid)",
      "after": "try await EventMetadataContext.withValue(CustomMetadata(operatorId: uid)) {\n    try await repository.delete(byId: id)\n}",
      "action": "Same as D1 for the delete overload."
    },
    {
      "id": "D3",
      "kind": "removed",
      "mechanical": true,
      "scope": "hand-written EventTypeMapper implementations",
      "before": "switch eventData.mappingClassName { … }",
      "after": "switch eventData.eventType { … }",
      "action": "`RecordedEvent.mappingClassName` is removed. Replace with the KurrentDB-native `eventData.eventType` (populated from `DomainEvent.eventType` at write time, so case labels still match the Swift type name)."
    },
    {
      "id": "D4",
      "kind": "removed",
      "mechanical": false,
      "scope": "any read of RecordedEvent.userId",
      "before": "let uid = recordedEvent.userId",
      "after": "// decode metadata into your schema, or read event.metadata after mapping",
      "action": "`RecordedEvent.userId` is removed. To recover the operator: after the mapper fills `event.metadata`, read `event.metadata?.operatorId` (when using CustomMetadata), or decode `recordedEvent.customMetadata` into your own EventMetadata type."
    },
    {
      "id": "D5",
      "kind": "removed",
      "mechanical": false,
      "scope": "construction and field access of CustomMetadata",
      "before": "CustomMetadata(className: \"X\", external: [\"userId\": uid])  /  meta.className  /  meta.external",
      "after": "CustomMetadata(operatorId: uid)  /  meta.operatorId",
      "action": "CustomMetadata is rewritten to a single-field struct `{ public let operatorId: String }`. The `className` and `external` fields and the old initializer are GONE. If you relied on `external` for arbitrary key/values, define your own `EventMetadata` struct instead (see N1)."
    },
    {
      "id": "N1",
      "kind": "new",
      "mechanical": false,
      "scope": "projects that need metadata fields beyond operatorId",
      "after": "struct AuditMetadata: EventMetadata {\n    let operatorId: String\n    let tenantId: String\n    let correlationId: String\n}",
      "action": "`EventMetadata` is a new marker protocol (`Codable & Sendable`, no required fields). Define your own metadata schema by conforming to it. This becomes your `Store.Metadata` and the `M` in `EventMetadataContext`."
    },
    {
      "id": "N2",
      "kind": "new",
      "mechanical": false,
      "scope": "Usecase entry points that previously passed external/userId",
      "after": "try await EventMetadataContext.withValue(metadata) { /* repository work */ }",
      "action": "`EventMetadataContext` is the new ambient carrier. Set it ONCE at the Usecase entry; nested repository.save calls read it automatically via structured concurrency. API: static `withValue(_:operation:)` and static `current`."
    },
    {
      "id": "U1",
      "kind": "unchanged",
      "scope": "DomainEvent protocol and all event structs",
      "note": "DomainEvent still declares `associatedtype Metadata: Codable` and `var metadata: Metadata? { get set }`. Generated event structs still emit `typealias Metadata = CustomMetadata`. No change needed to event definitions — but note CustomMetadata's shape changed (see D5)."
    },
    {
      "id": "U2",
      "kind": "unchanged",
      "scope": "AggregateRoot, Usecase, DomainEventBus, ReadModel, EventSourcingProjector.apply",
      "note": "Domain layer is untouched. `apply(readModel:events:)` signature unchanged. No migration needed for aggregates, use cases, or projectors' projection logic."
    },
    {
      "id": "U3",
      "kind": "unchanged",
      "scope": "EventStore.fetchEvents return shape",
      "note": "fetchEvents still returns `(events: [any DomainEvent], latestRevision: UInt64)?`. No streaming change."
    }
  ],
  "downstreamProcedure": [
    "Bump the swift-ddd-kit dependency requirement to 1.0 in Package.swift.",
    "Apply R1: rename protocol references EventStorageCoordinator -> EventStore.",
    "Apply R2 + R3: in every EventSourcingRepository / EventSourcingProjector conformer, rename `StorageCoordinator` typealias -> `Store`, `coordinator` property -> `store`, `init(coordinator:)` -> `init(store:)`.",
    "Decide the metadata schema: keep `CustomMetadata` (now { operatorId }) or define your own EventMetadata struct (N1).",
    "Apply S1 + S2: add the metadata generic argument to every KurrentStorageCoordinator / InMemoryStorageCoordinator usage.",
    "Apply S3 if the project has a custom EventStore implementation.",
    "Apply S4 + S5 + D1 + D2: rewrite every save/delete call site — drop external/userId args, wrap in EventMetadataContext.withValue where metadata is needed.",
    "Apply D3: in hand-written mappers, switch eventData.mappingClassName -> eventData.eventType.",
    "Apply D4 + D5: fix CustomMetadata construction/field access and any RecordedEvent.userId reads.",
    "If generated mappers/events are committed to the repo, regenerate them (or rebuild so the SwiftPM plugin regenerates).",
    "Build; resolve remaining compiler errors; run the test suite."
  ]
}