Module source 

Deterministic Git and snapshot source manifests. Deterministic source selection for remote builds.

Snapshot inputs are limited to the selected project tree, a small set of workspace build files, and caller-selected workspace-relative paths. Source paths must use slash separators and cannot be absolute, drive-prefixed, UNC, traversing, Windows-reserved, or normalization/case-colliding. Original UTF-8 names are retained while NFC-plus-lowercase collision keys protect materialization on normalizing or case-insensitive filesystems.

.ferryignore is read only at the workspace and project roots. Its safe subset accepts blank lines, hash-prefixed comments, and literal relative paths. A trailing slash is accepted; every rule excludes both the literal path and its descendants. Negation, glob syntax, escaping, absolute paths, whitespace at line edges, and non-portable names are rejected. Ignore rules can never re-include built-in sensitive paths. Caller exclusions use the same portable workspace-relative path model and take precedence over selected roots and ignore rules. The workspace root itself (.) cannot be excluded. Sensitive paths take precedence over all caller policy and are reported without traversing their contents.

Source ZIPs contain manifest files only: no embedded manifest, directory entries, links, or platform metadata beyond one normalized executable bit. ZIP metadata is fixed and entries follow manifest order, producing identical bytes for identical inputs. The separately transported manifest remains the worker’s source of truth. Hard-linked source files are refused on Unix and Windows. Windows link counts are queried from retained file handles so path replacement cannot substitute the object whose link state is inspected. Callers may supply portable executable-mode metadata for selected files; this carries executable intent from filesystems which do not expose Unix mode bits. A live Unix executable bit is never cleared by portable metadata.

Structs

GitSnapshotDescriptor

Strict binding for one operation-scoped GitHub dirty-source snapshot.

PlannedSourceFile

One local file selected by a bundle plan.

SourceArchive

Integrity descriptor for the deterministic source ZIP transport.

SourceArchiveLimits

Bounds enforced for source ZIP transport and extraction.

SourceBundleDescriptor

Versioned binding between one deterministic source ZIP and its manifest.

SourceBundlePlan

Deterministic source selection and local inputs needed to materialize it.

SourceBundleRequest

Local request used to select source for a snapshot.

SourceLimits

Resource bounds applied while selecting or verifying snapshot source.

SourceManifest

Canonical description of a source snapshot.

SourceManifestEntry

One content-addressed regular file in a source manifest.

Enums

IgnoreRuleReason

Reason a .ferryignore line was rejected.

PortablePathReason

Portable-path validation failure.

SourceError

Source planning or verification failure.

SourceLimitKind

Resource limit that was exceeded.

SourceMode

How a remote provider obtains source input.

Constants

GIT_SNAPSHOT_ARCHIVE_PATH

Fixed source archive path in a Git snapshot orphan commit.

GIT_SNAPSHOT_DESCRIPTOR_PATH

Fixed source descriptor path in a Git snapshot orphan commit.

GIT_SNAPSHOT_DESCRIPTOR_SCHEMA_VERSION

Current Git snapshot descriptor schema.

GIT_SNAPSHOT_REF_PREFIX

Private custom namespace for operation-scoped source snapshot commits.

GIT_SNAPSHOT_TREE_PATHS

Exact sorted regular-file tree required in a Git snapshot orphan commit.

MAX_GIT_SNAPSHOT_BYTES

Maximum complete payload of one GitHub dirty-source snapshot orphan commit.

MAX_GIT_SNAPSHOT_DESCRIPTOR_BYTES

Maximum canonical Git snapshot descriptor size, including its final newline.

MAX_SOURCE_BUNDLE_DESCRIPTOR_BYTES

Maximum canonical source-bundle descriptor size, including its final newline.

MAX_SOURCE_TRAVERSAL_ENTRIES

Defensive ceiling for selected directory entries and manifest path nodes.

SOURCE_BUNDLE_DESCRIPTOR_SCHEMA_VERSION

Current source-bundle descriptor schema.

Functions

canonical_git_snapshot_descriptor_bytes

Encode a validated Git snapshot descriptor in its one canonical byte representation.

create_source_bundle_archive

Create and atomically publish a deterministic source ZIP.

git_snapshot_archive_limits

Return strict source and ZIP limits for GitHub dirty-source snapshots.

git_snapshot_ref

Derive the only allowed Git snapshot ref for an operation.

plan_source_bundle

Select allowed source files and compute a deterministic manifest.

validate_source_manifest

Validate canonical ordering, bounds, paths, and digests in a manifest.

verify_and_extract_source_bundle

Verify and extract an untrusted source ZIP below a fresh destination.

verify_and_extract_source_bundle_with_parent_handle

Verify and extract an untrusted source ZIP using an already retained exact destination-parent handle instead of reopening that parent by pathname.

verify_materialized_bundle

Verify an already materialized bundle directory against a manifest.

verify_source_bundle_plan

Re-scan a plan’s original inputs and require an exact manifest match.

verify_source_manifest

Re-scan a request and require an exact match with an expected manifest.

write_source_bundle_descriptor_file

Validate and atomically publish a source-bundle descriptor as canonical JSON.