working_copy: Add LockedWorkingCopy::set_workspace_annotations hook

[rayaq-siddiqui]

This introduces a mechanism to pass metadata and annotations to a working-copy backend when its checkout is updated.

Specifically:

• Adds a WorkspaceAnnotations struct to hold the checkout metadata (currently the associated CommitId).
• Adds a set_workspace_annotations method to the LockedWorkingCopy trait, allowing backends to be notified of these updates. It defaults to a no-op for backends that do not track this state (like LocalWorkingCopy).
• Invokes this new hook during snapshot_working_copy in the CLI after the working-copy commit is updated.

Checklist

If applicable:

• I have updated CHANGELOG.md
• I have updated the documentation (README.md, docs/, demos/)
• I have updated the config schema (cli/src/config-schema.json)
• I have added/updated tests to cover my changes
• I fully understand the code that I am submitting (what it does,
  how it works, how it's organized), including any code drafted by an LLM.
• For any prose generated by an LLM, I have proof-read and copy-edited with
  an eye towards deleting anything that is irrelevant, clarifying anything
  that is confusing, and adding details that are relevant. This includes,
  for example, commit descriptions, PR descriptions, and code comments.

[PhilipMetzger]

I guess this is the thing @hooper asked some questions about in the Discord. Anyway to adhere to our commit style guidelines drop the conventional commit feat(...) and just use working_copy: <title>

[hooper]

This is actually different from the problem I mentioned on Discord a few weeks ago, but it has a very similar shape. That older one (passing operation attributes from the working copy implementation) seemed less controversial, but I wanted to get some early feedback on this new one in case we missed a nicer way to do it. I haven't checked if this one is as tricky to test, but that's a consideration in addition to performance.

[PhilipMetzger]

That older one (passing operation attributes from the working copy implementation) seemed less controversial

I agree.

but I wanted to get some early feedback on this new one in case we missed a nicer way to do it.

While I currently don't really have an idea on how to do it in a nicer way, the first thing which is surely a trade-off to make is that the Annotations statically encode all information (i.e the commit id) vs just having a set of strings downstreams can or cannot care about.

And if this is a static schema for all of Google I don't really think it should live upstream (that's a personal opinion).

[martinvonz]

I would have guessed that we could pass the commit id to LockedWorkingCopy::finish() instead of adding a new set_workspace_annotations() method. Why does that not work? I didn't quite follow the explanation in the commit description.

[rayaq-siddiqui]

Are you suggesting to pass WorkspaceAnnotations into finish()? For example:

    async fn finish(
        self: Box<Self>,
        operation_id: OperationId,
        annotations: WorkspaceAnnotations<'_>,
    ) -> Result<Box<dyn WorkingCopy>, WorkingCopyStateError>;

I believe this would work. I have not tested it yet.

The initial motivation for set_workspace_annotations() was to keep finish() focused strictly on operation finalization. That said, bundling checkout metadata into finish() makes sense if we'd prefer to avoid adding a separate method to LockedWorkingCopy. Thoughts?

[rayaq-siddiqui]

Or even:

    async fn finish(
        self: Box<Self>,
        operation_id: OperationId,
        wc_commit_id: CommitId,
    ) -> Result<Box<dyn WorkingCopy>, WorkingCopyStateError>;

And removing the WorkspaceAnnotations struct?