Story
As someone committing staged changes from an executable document, I want to omit as when I do not need the new commit's object ID, so the common commit form does not require an otherwise unused binding.
Example
This ordinary run creates a commit whose message comes from the component's content:
xmd run -e '<Git.Commit>Adding AGENTS.md</Git.Commit>'
It succeeds without rendering or binding the commit ID.
An author who needs that ID can still capture it:
<Git.Commit as="commitId">Adding AGENTS.md</Git.Commit>
Current gap
<Git.Commit> returns the new commit's full object ID, and the general value-component rule currently requires every returned value to be captured with as. As a result, the first example is refused before the commit runs:
<Git.Commit /> declares `returns`, so it renders nothing and must be invoked with `as`: <Git.Commit as="binding" />.
Creating the commit is the component's primary outcome. Its object ID is an optional receipt for documents that need to refer to it later, so requiring every caller to invent and retain a binding makes the less common form mandatory. The syntax catalog already describes <Git.Commit>'s as as optional, but validation and execution do not honor that contract.
Contract
as is optional for <Git.Commit> in ordinary and workflow runs, for both its self-closing and paired forms.
Without as, <Git.Commit> performs the same commit operation and renders nothing. The new commit's object ID is validated at the component boundary and then discarded by the caller.
With as, the existing behavior remains: the binding receives the new commit's full object ID and the component renders nothing.
The component's message rules do not change. A message may come from the message prop, rendered content, or both, and paired content finishes expanding before the commit begins.
Optional capture is an explicit part of a component's contract, not a relaxation for every component that declares returns. Value-only components whose result is their primary outcome, such as <Glob>, continue to require as. Static document validation, runtime expansion, and xmd syntax read the same capture requirement.
Git staging, identity, signing, hooks, transaction, replay, journaling, and failure behavior do not change. In particular, a workflow run retains the successful Git effect whether or not the document binds its returned object ID.
Acceptance
<Git.Commit>Adding AGENTS.md</Git.Commit> creates the commit without an as diagnostic, renders nothing, and uses Adding AGENTS.md as the commit message.<Git.Commit message="Adding AGENTS.md" /> creates the same commit without requiring a binding.<Git.Commit as="commitId">Adding AGENTS.md</Git.Commit> continues to bind the resulting full object ID.- Ordinary runs and workflow runs accept the unbound forms and retain their existing Git behavior.
xmd validate accepts an otherwise valid unbound <Git.Commit> invocation.- A value-only component such as
<Glob> is still refused without as.
xmd syntax Git.Commit describes as as optional, matching validation and execution.architecture.md, specs/workflow-workspace-spec.md, and the value-component contract in specs/executable-mdx-spec.md describe optional result capture without weakening components that still require it.
Evidence
Run the focused component, validation, ordinary-run, workflow, and syntax suites:
deno task test packages/core/tests/document-validation.test.ts packages/workflow/tests/git-commit.test.ts packages/workflow/tests/run-composition-ambient.test.ts packages/cli/tests/inline-cli.test.ts packages/cli/tests/syntax-cli.test.ts
The regression evidence includes paired and self-closing commits without as, capture when requested, an unbound value-only negative control, and agreement between validation, execution, and syntax inspection.
Related
Story
As someone committing staged changes from an executable document, I want to omit
aswhen I do not need the new commit's object ID, so the common commit form does not require an otherwise unused binding.Example
This ordinary run creates a commit whose message comes from the component's content:
xmd run -e '<Git.Commit>Adding AGENTS.md</Git.Commit>'It succeeds without rendering or binding the commit ID.
An author who needs that ID can still capture it:
Current gap
<Git.Commit>returns the new commit's full object ID, and the general value-component rule currently requires every returned value to be captured withas. As a result, the first example is refused before the commit runs:Creating the commit is the component's primary outcome. Its object ID is an optional receipt for documents that need to refer to it later, so requiring every caller to invent and retain a binding makes the less common form mandatory. The syntax catalog already describes
<Git.Commit>'sasas optional, but validation and execution do not honor that contract.Contract
asis optional for<Git.Commit>in ordinary and workflow runs, for both its self-closing and paired forms.Without
as,<Git.Commit>performs the same commit operation and renders nothing. The new commit's object ID is validated at the component boundary and then discarded by the caller.With
as, the existing behavior remains: the binding receives the new commit's full object ID and the component renders nothing.The component's message rules do not change. A message may come from the
messageprop, rendered content, or both, and paired content finishes expanding before the commit begins.Optional capture is an explicit part of a component's contract, not a relaxation for every component that declares
returns. Value-only components whose result is their primary outcome, such as<Glob>, continue to requireas. Static document validation, runtime expansion, andxmd syntaxread the same capture requirement.Git staging, identity, signing, hooks, transaction, replay, journaling, and failure behavior do not change. In particular, a workflow run retains the successful Git effect whether or not the document binds its returned object ID.
Acceptance
<Git.Commit>Adding AGENTS.md</Git.Commit>creates the commit without anasdiagnostic, renders nothing, and usesAdding AGENTS.mdas the commit message.<Git.Commit message="Adding AGENTS.md" />creates the same commit without requiring a binding.<Git.Commit as="commitId">Adding AGENTS.md</Git.Commit>continues to bind the resulting full object ID.xmd validateaccepts an otherwise valid unbound<Git.Commit>invocation.<Glob>is still refused withoutas.xmd syntax Git.Commitdescribesasas optional, matching validation and execution.architecture.md,specs/workflow-workspace-spec.md, and the value-component contract inspecs/executable-mdx-spec.mddescribe optional result capture without weakening components that still require it.Evidence
Run the focused component, validation, ordinary-run, workflow, and syntax suites:
deno task test packages/core/tests/document-validation.test.ts packages/workflow/tests/git-commit.test.ts packages/workflow/tests/run-composition-ambient.test.ts packages/cli/tests/inline-cli.test.ts packages/cli/tests/syntax-cli.test.tsThe regression evidence includes paired and self-closing commits without
as, capture when requested, an unbound value-only negative control, and agreement between validation, execution, and syntax inspection.Related
<Git.Commit>underxmd run#750 is the initial-commit workflow in which this independent UX problem was encountered.