Module thread_materialize 

Pure thread materialization planning.

Owns decision logic for the heddle start / heddle thread start materialization path once a concrete ThreadMode is known:

• checkout path layout (explicit --path vs managed default)
• ordered materialize step sequence (create dir, copy tree, manifest, …)
• typed start-transaction effect kinds and reverse cleanup lists
• target-dir claim → checkout / self-created-dir rewind actions
• path safety vs .heddle/threads layout and relative-path normalization
• empty-dir adoption / claim-intent pure validators
• effect staging preconditions (claim established, shared-target present)
• classification of mid-apply anyhow failures into HeddleError
• reflink vs full-copy policy for bytes-on-disk checkouts
• cargo --shared-target redirect and advisory flags

Filesystem clonefile/copy, mount RPCs, cargo-config writes, and the start_atomic transaction stay CLI-owned. Callers resolve host/config facts first, then invoke these helpers.

Structs

CheckoutPathPlan

Pure plan for where a new thread checkout should land.

StartEffectStagingFacts

Caller-supplied facts for pure start-effect staging gates.

StartTransactionPlan

Typed start-transaction plan: ordered effect kinds + mode flags.

ThreadMaterializePlan

Structured pure plan for the start materialization path.

Enums

CheckoutCopyPolicy

How a bytes-on-disk checkout should populate the tree.

CheckoutRewindPlan

Pure checkout-dir rewind action for a settled (or absent) target claim.

CreateDirAttempt

Outcome of a pure-facing create_dir attempt the caller reports.

MaterializeStep

One step in the atomic start materialization sequence.

RelativePathNormalizeError

Failures from pure relative-remainder normalization.

SelfCreatedDirRewindPlan

Pure self-created target-dir removal action (the create-step inverse).

SharedTargetRedirectDecision

Pure decision for whether --shared-target should write a cargo target-dir redirect after checkout materialize.

StartCleanupStep

One reverse-order cleanup action implied by a successfully applied effect.

StartEffectKind

Payload-free kind of a durable effect the start transaction can stage.

StartEffectPreconditionError

Why a planned effect must not run its FS forward yet.

TargetDirClaimKind

What the target-dir claim established about the worktree leaf (pure).

TargetDirCreateIntent

Plan-time intent for the create-target-dir step (before FS create/adopt).

TargetLeafRefusal

Why a leaf cannot be adopted as an empty directory claim.

TargetLeafShape

Observed shape of the worktree leaf (caller supplies FS facts).

ThreadsRootPathClass

Pure classification of a candidate checkout path vs heddle layout.

ThreadsRootPathSafetyError

Failures from pure threads-root / heddle-storage path safety checks.

Constants

ADVISORY_ACTIVE_HEAVY_THREAD_THRESHOLD

Active heavy (solid/materialized) threads at or above which a --shared-target heads-up is emitted when starting another heavy thread in a Rust workspace without the flag.

Functions

append_safe_relative_components

Append unresolved remainder components onto a resolved base.

claim_kind_after_empty_dir_adoption

Pure claim kind once empty-dir adoption is validated.

claim_kind_for_create_attempt

Pure claim kind after a successful create or a successful empty-dir adopt.

classify_materialize_error

Classify an anyhow error from a materialize/hydrate helper into the HeddleError the start transaction’s Result requires.

classify_path_vs_threads_root

Classify path relative to heddle_dir / threads_root.

classify_target_leaf_shape

Pure: classify metadata facts into a leaf shape (emptiness supplied when dir).

effect_requires_established_claim

Whether this effect writes through the claimed checkout leaf.

mode_is_bytes_on_disk

Whether a mode materializes a real on-disk checkout (vs a virtual mount).

path_components_are_safe

Whether a path component sequence is free of .. escape segments.

path_is_nested_in_reserved_region

Whether candidate falls inside reserved_dir, with optional exact exempt.

path_is_strict_descendant

Lexical strict descent: under root but not equal to it.

path_is_under_or_equal

Lexical containment: path is root or a strict descendant.

plan_checkout_copy_policy

Pure reflink-vs-copy policy from the planned thread mode.

plan_checkout_path

Plan the checkout path for a start once mode is known.

plan_checkout_rewind

Plan how the checkout rewind treats the target leaf for a claim outcome.

plan_hydrate

Whether --hydrate should run for this mode.

plan_materialize_steps

Convenience: ordered step list only.

plan_self_created_dir_rewind

Plan the create-step inverse for a settled (or absent) target claim.

plan_shared_target_redirect

Plan the --shared-target cargo-config redirect from pure inputs.

plan_start_cleanup

Build reverse cleanup steps for effects that successfully applied.

plan_start_transaction

Build the typed start-transaction plan from mode + post-decision flags.

plan_target_dir_create_intent

Pure create-intent from the plan-time target_dir_created observation.

plan_thread_materialize

Build the pure materialize plan from mode + post-decision flags.

plan_write_manifest

Whether a materialized-thread manifest sidecar should be written.

require_established_claim

Pure: whether a settled claim is present (writers/stage_checkout require it).

shared_target_redirect_applies

Whether plan_shared_target_redirect selected an apply.

shared_target_workspace_is_busy

Whether the workspace looks busy enough for a --shared-target heads-up (Rust + active heavy-thread population), independent of the start flags.

should_advise_shared_target

Whether start should print the --shared-target heads-up advisory.

should_warn_materialized_without_reflink

Whether start should warn that an explicit --workspace materialized will fall back to per-file copies on this host.

threads_root_path_layout_allowed

Whether classify_path_vs_threads_root accepts the layout class.

validate_empty_dir_adoption

Pure empty-dir adoption gate: only TargetLeafShape::EmptyDirectory ok.

validate_start_effect_preconditions

Pure preconditions an effect needs before its FS forward may run.

validate_threads_root_path_safety

Pure layout + reserved-region validation for a worktree target under the threads root / heddle storage policy.