@spec allows_global?(map() | nil) :: boolean()

Whether a policy explicitly allows the whole workspace.

@spec authorize_tool(map() | nil, String.t(), map(), String.t()) ::
  :allow | {:deny, map()} | {:error, map()}

Authorize one tool call under a bounded write policy.

@spec canonical_relative(String.t(), String.t()) ::
  {:ok, String.t()} | {:error, map()}

Canonical workspace-relative target for policy checks.

@spec from_file(String.t(), String.t()) :: {:ok, map()} | {:error, map()}

Load and normalize a bounded write policy JSON file.

@spec from_metadata(map() | nil) :: {:ok, map() | nil} | {:error, map()}

Rehydrate a runtime policy from safe metadata previously written to the Log.

The hash is recomputed from the canonical durable fields before the metadata is trusted. A mismatch means the Log projection was altered or came from an incompatible hash format and therefore fails closed.

@spec metadata(map() | nil) :: map() | nil

Machine-readable policy metadata safe for CLI/delegate JSON output.

@spec narrow_to_write_set(map(), [String.t()]) :: {:ok, map()} | {:error, map()}

Return a policy narrowed to the given write set.

@spec normalize(
  map(),
  keyword()
) :: {:ok, map()} | {:error, map()}

Normalize a bounded write policy map and compute stable metadata.

@spec rules_cover_path?([String.t()], String.t()) :: boolean()

Whether a workspace-relative path is covered by one of the given allow-style rules. Public single source for the policy glob semantics (#284 F2: the workflow apply step's write_set bound delegates here instead of hand-rolling a second matcher).

@spec validate_path_rules([String.t()], String.t()) :: :ok | {:error, map()}

Validate a list of allow/deny path rules against the policy glob grammar.

@spec validate_write_set_within_policy(map(), [String.t()]) :: :ok | {:error, map()}

Validate that every write_set rule is within a parent policy allow rule.