Skip to content

fix(build): qualify InterlinedDomain.Document so the app compiles on Xcode 27 - #99

Merged
Adron merged 1 commit into
devfrom
fix/xcode27-document-ambiguity
Sep 17, 2026
Merged

Adron merged 1 commit into
devfrom
fix/xcode27-document-ambiguity

Conversation

@Adron

@Adron Adron commented Sep 16, 2026

Copy link
Copy Markdown
Member

Summary

Closes #98. Merge this first — dev does not compile without it, so every other open PR is blocked behind it.

What happened

Xcode was updated on this machine at 12:23 today, mid-session. Builds from the same commit succeeded before it and failed after. The macOS 27 SDK adds a Document protocol to SwiftUI:

SwiftUI.Document:4:17: note: found this candidate
  public protocol Document : ReadableDocument, WritableDocument {

InterlinedDomain has exported a Document struct since M4. Any file importing both now has an ambiguous Document in scope — and that is every documents-feature view.

Eleven errors across eight files, all App/Features/**:

AI/AIDocumentSheet.swift · Documents/ConflictBannerView.swift
Documents/DocumentEditorView.swift · Documents/DocumentsListView.swift ×3
Documents/DocumentsRootView.swift ×2 · Documents/DocumentTemplatePickerView.swift
Documents/PublicUserDocumentsView.swift · Search/SearchRootView.swift

The last two only surfaced once the earlier ones stopped short-circuiting compilation, which is why the first error list was nine.

The view models are unaffected, and that is what makes the diagnosis unambiguous: they import Foundation, Observation and InterlinedDomain but not SwiftUI, and they compile untouched. It is exactly the SwiftUI-importing files.

The fix

Qualify the type at the use sites: InterlinedDomain.Document.

Every edit is a type position. No user-facing string, accessibility label, or other identifier containing the word "Document" is touched — the diff is eleven lines, each one a Document the compiler itself pointed at. The full diff is in the Files tab and is worth a glance precisely because a blanket find-and-replace here would have been wrong.

Rejected alternatives

Option Why not
Rename the domain type Document is the right name for it, and it is correct across Kit, Domain, Persistence and their tests. Renaming a core model to dodge a collision in one consumer is the tail wagging the dog.
A module-level typealias ILDocument Shorter at the use sites, but it gives one concept two names and the next reader has to learn they are the same thing.
Drop import SwiftUI Not available. These are views.

One explanatory note goes at the top of DocumentsListView.swift rather than eleven copies of the same paragraph.

Worth knowing

This is a standing hazard, not a one-off. Any domain type sharing a name with a SwiftUI symbol is one SDK update away from the same break. Nothing to do pre-emptively — but the diagnosis is now written down, so the next occurrence takes minutes rather than an afternoon.

Verification

On Xcode 27.0 (27A266a), macOS SDK 27.0:

  • xcodebuild build → ** BUILD SUCCEEDED **
  • xcodebuild test (App) → Executed 968 tests, with 0 failures · ** TEST SUCCEEDED **
  • swift test InterlinedDomain → Executed 1012 tests, with 0 failures
  • swift test InterlinedPersistence → Executed 140 tests, with 0 failures
  • swift test InterlinedKit --skip ContractTests → Executed 477 tests, with 0 failures (live ContractTests rate-limited from this session's recon; unmodified here)
  • Decision 0003 (anchored) → zero hits

No behaviour change — this is a compile fix.

Note for the other open PRs

#86, #87, #88, #89, #90, #92, #93, #94, #96 and #97 all branch from dev before this. Their gates were run before the Xcode update and were green at the time. Once this merges they will each need dev merged in to build on Xcode 27; nothing about their content is affected.

🤖 Generated with Claude Code

…Xcode 27

`dev` stopped building when Xcode was updated on this machine mid-session. The
macOS 27 SDK adds a `Document` protocol to SwiftUI —

    public protocol Document: ReadableDocument, WritableDocument

— which collides with the domain's `Document` struct in any file importing both.
That is every documents-feature view, and the same unchanged source went from
compiling to eleven `'Document' is ambiguous for type lookup` errors across eight
files.

Only the SwiftUI-importing files are affected, which is what makes the diagnosis
unambiguous: the view models import Foundation, Observation and InterlinedDomain
but not SwiftUI, and they compile untouched.

The fix is to qualify the type at the use sites. Three alternatives were
considered and rejected. Renaming the domain model is the tail wagging the dog —
`Document` is the right name, and it is correct across Kit, Domain, Persistence
and their tests. A module-level typealias would shorten the use sites at the cost
of giving one concept two names, so the next reader has to learn they are the
same thing. Dropping `import SwiftUI` is not available; these are views.

Every edit is a type position. No user-facing string, accessibility label or
other identifier containing the word Document is touched — the diff is eleven
lines, each one a `Document` that the compiler itself pointed at.

Worth knowing rather than fixing: this is a standing hazard. Any domain type
sharing a name with a SwiftUI symbol is one SDK update away from the same break,
and the diagnosis is written down at the top of DocumentsListView so the next
occurrence takes minutes.

Refs #98

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Adron

Adron commented Sep 16, 2026

Copy link
Copy Markdown
Member Author

⚠️ Worth knowing in review: CI could not have caught this, and still cannot

.github/workflows/ci.yml pins:

XCODE_VERSION: "26.3"

The break is an Xcode 27 SDK change. So:

  1. CI was green on dev the entire time it did not compile locally. Every PR in this stack shows 8/8 SUCCESS — including the ones whose gates I ran before the Xcode update. That is not CI being wrong; it is CI testing a different toolchain than the one on the development machine.
  2. This fix is safe on both. Explicit module qualification (InterlinedDomain.Document) is valid on 26.3 and 27 alike — it is not conditional, and there is no availability guard. CI confirms: 8/8 green.
  3. The divergence is the standing risk. With CI on 26.3 and local on 27, the next SDK-level collision will again be invisible to CI and will again surface as "dev suddenly does not build on my machine".

Worth deciding (not something I should decide)

Either bump XCODE_VERSION to 27 so CI tracks the machines people actually build on, or pin the local toolchain so the two agree. Leaving them two majors apart means CI is answering a question nobody is asking.

I have not changed the pin in this PR — bumping the CI toolchain is a separate decision with its own blast radius, and this PR should stay a compile fix.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant