Is the problem that saving a new document as a draft makes it ambiguous what the "live version" of the page should look like?

Largely, yes. I think there's one technical problem and one product problem:

The technical problem is that if we implement hasUnpublishedDraft() on Document like this:

public function hasUnpublishedDraft() {
  return ($this->getContent()->getVersion() < $this->getMaximumVerison());
}

...then there's no easy/obvious way to set things up in the database to make this return true for a "new + draft" document, since there's only going to be one content object and thus only one version, and 1 (the version of that first content object) is not less than 1 (the maximum version of any content object on the document). This is tractable (we could write a fake content object, we could have some special flag, whatever) but I think we need to add some amount of complexity to handle it.

The other problem is as you suggest:

• What does the "live page" show when you look at it and there's no published version?
• What does it show in the document hierarchy?

I think we could find reasonable answers to these questions, but I'm generally not completely sure that this draft feature is actually good / non-confusing / reasonable / useful as currently written, so I want to kind of float out a minimum take on it and see what feedback looks like. Most of the other changes in this series are probably good things whether "draft" sticks around in this form or not (database fixes, more modern transaction handling, better UI navigation between versions, etc) but I'd like a little more confirmation that I'm on the right track with "Draft" (even if that's just using it for a bit myself and having a reasonable experience with it).

One related issue is that there's no way to find documents which return true from (hypothetical) hasUnpublishedDraft() via a DocumentQuery, so we can't add features like "show drafts I'm working on" easily. If we added something like that, it might make it easier to answer "what happens in the hierarchy?" -- if the answer to "What shows in the hierarchy for new + draft documents?" is "nothing", we need some other way for users to get back to them, finish editing them, and eventually publish them.

In D19663#243397, @epriestley wrote:

One related issue is that there's no way to find documents which return true from (hypothetical) hasUnpublishedDraft() via a DocumentQuery...

Oh, that makes sense, because drafts aren't a first-class entity; they're just documents that have had a "don't actually bump the version" transaction applied to them at some point. Eventually (if drafts survive at all), I guess we'll end up with a column on phriction_document like is_draft? (I'm just wargaming this out loud to understand how you imagine this feature would evolve).

Yeah -- some possible approaches I haven't thought about too much:

• Just an is_draft thing on Document.
• There's an existing status on Document (which stores moved, deleted) and maybe that gets a "draft" value? (Can you have a "draft" deleted document? Today, the answer is "no".)
• When you apply a "draft", write a "UserWorkingOnDraft" edge. When a document is published, remove it. Then we can query for "drafts you're working on" even if you aren't the most recent editor. But this maybe gets a little weird with "publish-revert" operations, long-lived drafts, drafts you want to disavow, etc.
• Maybe is_draft on the Content? That's a slightly simpler version of "UserWorkingOnDraft" but it might not be quite flexible enough.
• We can probably make Query find "has draft" without any schema changes with multiple clever JOINs, although I'd guess the query plan for this will be garbage.

I suppose we could cheat like this if we want to explore draft queries:

SELECT d.* FROM phriction_document d JOIN phriction_content draft
  ON draft.documentPHID = d.phid
  AND draft.version = d.maxVersion
  AND d.contentPHID != draft.phid

The query plan probably isn't great but I don't think it's explosively bad and Phriction document tables are probably not huge in reasonable cases. That's not good enough to get "drafts you've contributed to", but AND draft.authorPHID = <viewerPHID> could get "drafts you've personally written".