Skip to content

WF-0123: Unmaterialized file buffers and external edit frontier #159

Closed
Closed
WF-0123: Unmaterialized file buffers and external edit frontier#159
Labels
bugSomething isn't workingdocumentationImprovements or additions to documentationenhancementNew feature or request
Milestone
Jim Strand/Braid UX

Description

@flyingrobots
flyingrobots
opened on Jun 26, 2026

Problem

:edit foo.txt currently obstructs when foo.txt does not exist on disk. That treats filesystem materialization as the precondition for a causal buffer, which conflicts with Jim/Echo semantics.

Jim should be able to create a causal buffer and local strand for a missing path, let the user edit immediately, and only materialize foo.txt onto disk when the user saves/exports.

Design Direction

  • Missing-path :edit foo.txt opens an unmaterialized causal buffer, not an error.
  • The buffer remains available in Echo/WSC causal history even if it has never been saved to disk.
  • Save/export materializes the current chosen basis to foo.txt.
  • If an external process creates or edits foo.txt, Jim records that as an External Edit intent on the canonical worldline.
  • If the external edit advances the frontier while the user has local strand changes, Jim should notify the user and offer a braid/preview reconciliation flow instead of silently overwriting either side.

Scenario Cycles

  1. Missing-path open creates an unmaterialized causal buffer.
  2. Save materializes a previously unmaterialized buffer and handles path collisions.
  3. External filesystem changes enter causal history as External Edit intents.
  4. Frontier-advanced UX lets the user braid external mainline changes with local strand edits.

Acceptance Sketch

  • :edit foo.txt succeeds when foo.txt does not exist.
  • foo.txt is not written to disk until :write, :wq, or an explicit export/materialization command.
  • Closing/reopening Jim can recover the unmaterialized causal buffer from retained history.
  • A later external foo.txt creation is not ignored and not treated as the user's local strand.
  • Save detects disk/mainline frontier mismatch and routes through conflict/braid UX.
  • History/worldline UI distinguishes unmaterialized local path binding, canonical disk-backed frontier, external edit intent, and active braid preview.

Notes

This is a design/spec umbrella. Implementation should follow after the scenario matrix is explicit enough to avoid unsafe save/open behavior.

Activity

  1. flyingrobots
    added this to the Jim Strand/Braid UX milestone on Jun 26, 2026
  2. flyingrobots
    added
    bugSomething isn't working
    documentationImprovements or additions to documentation
    enhancementNew feature or request
    on Jun 26, 2026

  3. coderabbitai commented on Jun 26, 2026

    @coderabbitai
    coderabbitaibot
    on Jun 26, 2026 – with coderabbitai
    🔗 Related PRs

    #1 - Refine jedit pane shell [merged]
    #23 - feat(echo): add Echo release gate witness [merged]
    #115 - Define Vim target usability workflows [merged]
    #135 - Docs: lock Jim causal roadmap [merged]

    📝 Issue Planner

    Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.

    • Create Plan
    🧪 Issue enrichment is currently in open beta.

    You can configure auto-planning by selecting labels in the issue_enrichment configuration.

    To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

    issue_enrichment:
  auto_enrich:
    enabled: false

    💬 Have feedback or questions? Drop into our discord!

  4. flyingrobots commented on Jun 27, 2026

    @flyingrobots
    flyingrobots
    on Jun 27, 2026
    OwnerAuthor

    Closed as the WF-0123 foundation slice landed through PR #160: #160

    Landed scope:

    • missing-path :edit foo.txt opens an unmaterialized Echo-backed buffer instead of requiring a host file;
    • opening a missing path does not write the file on disk;
    • :write materializes a missing-open buffer only when the host path remains compatible;
    • save/export preflights host fingerprints for existing files and missing-open paths;
    • externally changed/deleted/path-kind-conflicted host paths block materialization instead of being overwritten;
    • blocked materialization does not mark the buffer clean/materialized;
    • blocked :wq does not quit;
    • WSC settlement/recovery/export refuses bounded readings as materializable text;
    • inactive and unmaterialized buffers survive file switching through the buffer registry;
    • Graft drawer and docs now name projection/materialization posture honestly.

    Remaining work was split into focused follow-up issues:

    Related runtime doctrine follow-up:

    This issue was intentionally an umbrella. Keeping it open after #160 would make the roadmap ambiguous, so the remaining work now has separate issue boundaries.

  5. flyingrobots
    closed this as completedon Jun 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions