@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 recorded metadata is intentionally enough for later diagnostics or live-handle reattachment without trusting a prompt or model-supplied override. It preserves the original hash instead of recomputing it from a lossy projection.

@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 validate_write_set_within_policy(map(), [String.t()]) :: :ok | {:error, map()}

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