lanework/Kanban/Changes/ChangeNarration.swift

import Foundation

/// Harvested 2026-08-08 from `Kanban/Git/` per `strategy/01-git-excision.md`, with its git ties
/// severed — this is the designated core of the future activity feed / foreign-change journal. The
/// "previous snapshot" a narration request carries is supplied by the caller by contract: the git
/// stack supplied it from HEAD, and the journal will supply it from memory/snapshots.

// MARK: - Authorship

/// Which of the three classes a commit is — the axis the message engine is allowed to know about.
///
/// The composer receives it because 06-history-undo.md ▸ Commit messages gives one rule that turns
/// on it (the root commit's fixed subject) and one that deliberately does not: "**Foreign commits
/// speak the same vocabulary.** Origin lives in the author field (structural attribution), not in
/// message prose — a foreign move reads 'Move card …' exactly like an app-mediated one". The
/// composer card therefore gets the fact and is expected to ignore it for phrasing; having it means
/// it never has to be plumbed later, and having it *named* means the rule about not using it has
/// something to point at.
public enum ChangeAuthorship: Sendable, Equatable {
    /// The user acting through the app.
    case user
    /// A scheduled heal's own commit (ruled 2026-07-29).
    case heal
    /// Everything else, carrying the display name it will be recorded under.
    case foreign(String)
}

// MARK: - The request

/// Everything the message engine is handed for one commit.
///
/// **A struct rather than an argument list**, because the point of this seam is that the semantic
/// composer plugs into it without reshaping the engine: any input it turns out to need joins this
/// type rather than every call site. It did need two — `previousSnapshot` and `agentGuideText`, both
/// below — and that is exactly what this shape was for.
///
/// **Everything here is a value, and that is the design.** The composer (`ChangeNarrator`) reads
/// no file and opens no repository: the flush resolves the environment once — the board as HEAD has
/// it, the board as the app has it, the guide's bytes — and the message is then a pure function of
/// this struct. Resolving once per *flush* rather than once per planned commit also means a
/// three-way-split window materializes HEAD's tree once, not three times.
public struct ChangeNarrationRequest: Sendable {

    /// The board this is a commit in.
    public let boardRoot: URL

    /// **The changed-path list** (06 ▸ Commit messages ▸ Non-snapshot files commit too: "beside the
    /// snapshot diff it receives the changed-path list, and non-snapshot paths compose *path-shaped
    /// events*"), narrowed to the paths *this* commit stages.
    public let changedPaths: [ChangedPath]

    /// Which class this commit is.
    public let authorship: ChangeAuthorship

    /// Whether this is the repository's first commit — the one commit with a subject of its own
    /// ("Initial board state", 06 ▸ Rules ▸ Abnormal repo states).
    public let isRootCommit: Bool

    /// **The current half** of the composer's "last-committed vs. current" diff — the board as the
    /// app last read it, or, where no store is attached, as the flush read it off disk itself.
    ///
    /// `nil` only when neither could answer: a board whose working tree does not load at all, which
    /// is a commit that will have to be described by its paths.
    public let snapshot: BoardModel?

    /// **The last-committed half** of the "last-committed vs. current" diff — supplied by the caller
    /// by contract; the narrator itself never reads this from anywhere. The retired git substrate
    /// materialized it from HEAD's tree; the journal will supply it from memory/snapshots.
    ///
    /// `nil` when the caller has nothing to diff against — a first window (where `isRootCommit`
    /// already says everything), or a stored state that did not load as a board.
    ///
    /// **A supplier reads it rather than carrying it forward** from the last window it described, and
    /// deliberately: the app is not the only writer, and catch-up after a period of not watching has
    /// no carried value to offer.
    public let previousSnapshot: BoardModel?

    /// **The board-root `CLAUDE.md` as it now reads**, when this commit touches it — the one
    /// non-snapshot file with a subject of its own ("Update agent guide (vN)", 06 ▸ Commit messages).
    ///
    /// The *text*, not the version: N is "a pure function of file content"
    /// (`AgentGuide.installedVersion`), and keeping the parse on the composer's side is what keeps
    /// that rule where the message vocabulary is. `nil` when the guide is not in this commit, cannot
    /// be read, or has been deleted.
    public let agentGuideText: String?

    /// **When each of this commit's comments was created** — keyed by the comment folder's
    /// board-root-relative path, as `ChangeNarrator.commentFolder(of:)` spells it.
    ///
    /// The second value on this struct that a *file* has to be read for, and it is here for
    /// `agentGuideText`'s reason exactly: "a commit's comment bullets sort chronologically — by the
    /// comments' own `created`, folder name on ties" (06 ▸ Rules ▸ Auto-commit, blessed 2026-07-31),
    /// and `created` lives in a comment's own `index.md` because comments are window-scoped and the
    /// board snapshot never carries them (01-storage-format.md § Enhanced schema). The flush resolves
    /// it once, off disk, and the engine stays a pure function of values.
    ///
    /// **Missing is normal, not a defect.** A comment whose folder left the tree in this very commit
    /// (the close purge), one whose `index.md` does not parse, one written by hand with no `created`
    /// at all — each is simply absent here and sorts after its dated siblings in folder-name order,
    /// which is `CommentThread.sorted`'s own fallback for the same field.
    public let commentTimestamps: [String: Date]

    public init(
        boardRoot: URL,
        changedPaths: [ChangedPath],
        authorship: ChangeAuthorship,
        isRootCommit: Bool,
        snapshot: BoardModel?,
        previousSnapshot: BoardModel? = nil,
        agentGuideText: String? = nil,
        commentTimestamps: [String: Date] = [:]
    ) {
        self.boardRoot = boardRoot
        self.changedPaths = changedPaths
        self.authorship = authorship
        self.isRootCommit = isRootCommit
        self.snapshot = snapshot
        self.previousSnapshot = previousSnapshot
        self.agentGuideText = agentGuideText
        self.commentTimestamps = commentTimestamps
    }
}

// MARK: - The seam

/// **What a commit says** (06-history-undo.md ▸ Commit messages).
///
/// The implementation is `SemanticChangeNarration` below, over `ChangeNarrator`: "a pure, testable
/// function" composing from a structural diff of two board snapshots, with the whole
/// Add/Delete/Move/Rename/Edit vocabulary, plural folding, path-shaped events for non-snapshot files,
/// and the trash pair. The protocol survives its interim purpose because it is still what lets a test
/// inject a fake and assert *when* a message was asked for without asserting what it said.
///
/// `Sendable` because composition runs off the main actor, inside the same detached task that stages
/// and commits — the message has to be in hand before `git_commit_create` is called, and none of the
/// work is main-actor work.
public protocol ChangeNarrating: Sendable {
    func narrative(for request: ChangeNarrationRequest) -> String
}

// MARK: - The wired composer

/// **The semantic composer**, and the seam's default.
///
/// A one-line conformance over `ChangeNarrator`, deliberately: the vocabulary is worth a file of
/// its own and nothing about it should have to know that a protocol exists. The type stays because
/// the seam takes an existential, and because a *named* default is what makes "the engine's composer
/// is the semantic one" assertable.
public struct SemanticChangeNarration: ChangeNarrating {

    public init() {}

    public func narrative(for request: ChangeNarrationRequest) -> String {
        ChangeNarrator.narrative(for: request)
    }
}