InvalidManifestException

Thrown when a decoded manifest array cannot be turned into a valid value object — a required field is absent, a version is not valid semver, or a field has the wrong type. Implements the framework marker {@see MilpaExceptionInterface} so hosts can catch every Milpa-originated error uniformly. Messages are technical English and name the value-object type, the offending field, and (where known) the record subject, so the failure points at the exact manifest entry.

public static function missingField(string $type, string $field, ?string $subject = null): self

A required field is absent (or empty).

Parameters

public static function invalidVersion(string $type, string $field, string $value, ?string $subject = null): self

A version field does not parse as a semantic version.

Parameters

public static function notAnArray(string $type, string $field, ?string $subject = null): self

A field expected to hold an array holds something else.

Parameters

public static function unexpectedValue(string $type, string $field, string $value, ?string $subject = null): self

A field holds a value outside the set the type accepts (e.g. an unknown enum case).

Parameters

public static function invalidIsoDate(string $type, string $field, string $value, ?string $subject = null): self

A date/datetime field does not parse as an ISO-8601 value (relative expressions like "now" are rejected too — the resolver stays pure, so the clock must be explicit data, never an ambient read).

Parameters

public static function acceptedRiskWithoutReason(string $code): self

An accepted risk was declared without a reason. Accepting a risk without saying why silences it, which is exactly what `acceptedRisks` exists to prevent — so the omission is a hard error.

Parameters

public static function acceptedRiskLegacyShape(string $value): self

The pre-0.2 bare-string `acceptedRisks` shape was used; the message teaches the object shape that replaced it (a code alone can never carry a reason, so it could only ever silence).

Parameters

public static function missingFile(string $path): self

The manifest file does not exist at the given path (an ingestion-layer failure — the path is the subject, since there is no decoded content to point at yet).

Parameters

public static function unreadableFile(string $path): self

The manifest file exists but could not be read from disk.

Parameters

public static function invalidJson(string $path, string $detail, ?Throwable $previous = null): self

The manifest file's contents are not valid JSON; `$detail` carries the decoder's reason.

Parameters

public static function malformed(string $path, string $detail, ?Throwable $previous = null): self

The manifest decoded but is structurally wrong; `$detail` (often a wrapped field-level message) says what, and the path says where — so a malformed manifest always names both.

Parameters